GC28-0629-0 
File No. $370-39 


OS/VS2 System Programming 
Systems Library: TSO 


VS2 Release 3 


First Edition (February, 1975) 


This edition, with OS/VS2 System Programming Library: Job Management, GC28-0627, and 
OS/VS2 System Programming Library: Supervisor, GC28-0628, obsoletes OS/VS2 System 
Programming Library: Job Management, Supervisor, and TSO, GC28-0682-0. 


This edition applies to release 3 of OS/VS2 and to all subsequent releases of OS/VS2 
until otherwise indicated in new editions or Technical Newsletters. Changes are 
continually made to the information herein; before using this publication in connection 
with the operation of IBM systems, consult the latest Virtual Storage Supplement to IBM 
System/360 and System/370 Bibliography, GC20-0001, for the editions that are applicable 
and current. 


Requests for copies of IBM publications should be made to your IBM representative or 
to the IBM branch office serving your locality. 


A form for readers comments is provided at the back of this publication. If the form 
has been removed, comments may be addressed to IBM Corporation, Programming 


Systems Publication, Department D58, Building 706-2, PO Box 390, Poughkeepsie, N.Y. 


12602. Comments become the property of IBM. 


© Copyright International Business Machines Corporation 1974,1975 


. 


Preface 


The information in this publication was extracted from OS/VS2 System 
Programming Library: Job Management, Supervisor, and TSO, GC28-0682. As 
of Release 3, the above book has been split into three separate publications. 
These books are now identified as OS/VS2 System Programming Library: 
TSO, GC28-0629; OS/VS2 System Programming Library: Job Management, 
GC28-0627; and OS/VS2 System Programming Library: Supervisor, 
GC28-0628. 


This publication describes the TSO facilities that can be influenced by the 
system programmer. 


Part 1: TSO Services discusses considerations in preparing for TSO 
processing, managing data sets needed by TSO, and writing exit routines to 
extend or modify the operation of TSO. 


Part 2: Reference — TSO Commands describes the TSO commands 
ACCOUNT and OPERATOR and their associated subcommands, which should 
be installation controlled. 


References to multiple virtual storage (MVS) pertain to OS/VS2 Release 2 
and subsequent releases. 
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Summary of Amendments 
for GC28-0629-0 
OS/VS2 Release 3 


TSO Services 


Was taken in its entirety from Part 3 of OS/VS2 System 
Programming Library: Job Management, Supervisor, and TSO. 
Major changes and additions to this data are as follows: 


TSO Allocation Suggestions 


Offers suggestions for improving TSO allocations. 


e Placement of user data sets in a LOGON Procedure. 
* Carefully choosing the DYNAMNBR parameter value in 
the EXEC statement. 


Space Allocation Using the EDIT Access Method 


Explains the alogrithms used in allocating EDIT's utility 
work data set space. 


« Existing data sets. 
« New data sets. 


Writing Installation Exits for the RENUM 
Subcommand of EDIT 


Expanded to cover the MOVE and COPY subcommands of 
EDIT. 


Executing Authorized Programs Under TSO 


Gives restrictions and exposures pertaining to the execution 
of authorized programs. 
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Part 1: TSO Services 


This chapter is intended for the programmers responsible for generating and maintaining a 
system with TSO. The chapter outlines how to do the following things: 


e Write the cataloged procedures used by TSO. 
| e Create, convert, and maintain the user attribute data set (UADS) and broadcast data set. 
e« Write an installation exit for the SUBMIT command processor. 
e« Write an installation exit for the STATUS, OUTPUT, and CANCEL command processors. 
e Write a LOGON pre-prompt exit. 
| «+ Write an installation exit for the COPY, MOVE and RENUM subcommands of EDIT. 
e« Write an exit for an installation-written syntax checker. 
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Preparing for TSO Processing 


After system generation, the system programmer must perform the following steps before a 
terminal user can log on: 


« Tailor the message control program (MCP) to suit the installation’s needs. See OS/VS2 
TCAM Programmer’s Guide. 


e Write the MCP cataloged procedure and include it in SYS1.PROCLIB. 
¢« Write LOGON cataloged procedure(s) and include them in SYS1.PROCLIB. 


e« Construct the IKJPRM0O member of SYS1.PARMLIB to set the terminal I/O controller TIOC 
parameters. See the discussion of IKJPRM00 in OS/VS2 System Programming Library: 
Initialization and Tuning Guide. 


e Include SYSI.CMDLIB in a LNKLSTxx member of SYSI.PARMLIB or in a LOGON cataloged 
procedure. For information on LNKLSTxx, see OS/VS2 System Programming Library: 
Initialization and Tuning Guide. 


e Create or convert the UADS and broadcast data sets. 


Note: No BRDR procedure is needed for MVS, since the background reader for submitted jobs 
has been replaced with a direct interface from the SUBMIT command to a job entry subsystem 
internal reader (INTRDR). 


Writing a Message Control Program Cataloged Procedure 


The cataloged procedure used to start an MCP specifies the MCP to be started through the 
PGM= operand of the EXEC statement. The MCP should be named IEDQTCAM; if a name 
other than IEDQTCAM is specified, the name must be added to the program properties table 
(PPT) and must be marked nonswappable. The PPT describes the environment that TCAM 
requires to operate properly. (See ‘Assigning Special Program Properties" in the OS/VS2 SPL: 
Job Management. Also, the EXEC statement must include the DPRTY parameter as 
DPRTY=(13,9). 


The cataloged procedure used to start the MCP also must define thé line addresses dedicated 
to TCAM. This is done by issuing the LINEGRP macro instruction (used in generating the MCP) 
to specify the ddname of the DD statements that define the communication lines as data sets. 
For more information, see OS/VS2 TCAM Programmer’s Guide. 
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Figure 1 shows a sample listing of cataloged procedures used to start MCPs. 








//MCP1 EXEC PGM=IEDQTCAM, TIME=1440 , REGION=128K,DPRTY=( 13,9) 

/ /LNGP2741 DD UNIT=021 FIRST LINE GROUP DATA SET 2741 

Ved DD UNIT=022 

// DD UNIT=023 

fd DD UNIT=024 

7] DD UNIT=025 

// DD UNIT=026 

J} DD UNIT=027 

Lf DD UNIT=028 

a DD UNIT=029 
DD UNIT=02A 

/ /LNGPTWX DD UNIT=02B SECOND LINE GROUP DATA SET TWX 
DD UNIT=02C 

pe DD UNIT=02D 

// DD UNIT=02E 

/ DD UNIT=02F 

//MCP2 EXEC PGM=LEDOTCAM, TIMF=1440, REGION=128K,DPRTY=( 13,9) 

//DIAL5041 DD UNIT=021 LINE GROUP DATA SET 

JF DD UNIT=022 

// DD UNIT=023 

a DD UNIT=024 

ve, DD UNIT=025 

Pe, DD UNIT=026 

ve DD UNIT=027 

Ve DD UNIT=028 

Sh DD UNIT=029 

fi DD UNIT=02A 


Figure 1. Sample Listing of MCP Start Procedures 


Writing a LOGON Cataloged Procedure 


A LOGON cataloged procedure defines the system resources available to a terminal user, and 
defines or allows for dynamic allocation of all data sets used by a terminal user. Also, a 
LOGON procedure specifies which program is to be invoked after LOGON: the terminal monitor 
program (TMP) distributed with Multiple Virtual Storage (MVS) or an installation-written 
program. A LOGON cataloged procedure can be specified in the PROC operand of the LOGON 
command, supplied through an installation exit from the LOGON processor, or defined in the 
entry for the userid in UADS. (If more than one procedure is defined for a userid/ password 
combination, the procedure must be specified on the LOGON command.) For LOGON 
procedures to reside in a separate library: 


1. Code a PROCXx DD statement for the library in the JES2 procedure. 


2. Specify xx in the PROC=xx parameter for the &TSU job class in the JES2 initialization 
parameters, (See, ''JES2 Initialization" in OS/VS2 SPL: Initialization and Tuning Guide. 


LOGON cataloged procedures must reside in the data set defined in the procedure used to 
Start the primary job entry subsystem. This data set may be either SYS1.PROCLIB or a 
partitioned data set dedicated to LOGON procedures. 


Note: During LOGON, the step allocation routine does not wait for an unavailable volume. If 
this condition arises, the LOGON request fails immediately. 
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TSO Allocation Suggestions 


The following suggestions should improve TSO allocations: 


¢« Data sets the user wants for his TSO sessions should be placed in a LOGON procedure. 
This technique has these advantages: 


1. Allows volumes to be mounted. 


2. Provides recovery from an offline device condition. Messages tell the operator to 
‘VARY’ the device online. 


3. Saves repeated allocation and freeing of the same data set by successive commands in 
the same TSO session. 


e The DYNAMNBR parameter value in the EXEC should be carefully chosen. The value 
should be large enough so that it is not readily exceeded by dynamic allocation requests. 


Note that the maximum number of concurrently allocated resources for any TSO session 
is 1635. 


Note: The LOGON will take longer to complete, however, overall TSO performance should be 
better. 


EXEC Parameters 


The TMP distributed with MVS is named IKJEFTO1!. If an installation-written TMP is to be used 
for a particular procedure, its module name must be substituted for IKJEFTO1 in the PGM= 
operand in the EXEC statement. REGION= can be used to limit the amount of virtual storage 
obtained by variable-length GETMAINs. 


DYNAMNBR= is used to calculate the allowed number of concurrent allocations via dynamic 
allocation. If DYNAMNBR= is omitted, the number of allocations is determined by the number 
of DD DYNAM statements. If DD DYNAM statements and DYNAMNBR= are both present, the 
number of concurrent allocations equals the combined total. 


e The DYNAMNBR parameter value in the EXEC statement should be carefully chosen. The 
value should be large enough so that it is not readily exceeded by dynamic allocation 
requests. Note that the maximum number of concurrently allocated resources for any TSO 
session is 1635. 


If you need job step timing, include the TIME parameter on the EXEC statement in the 
LOGON procedure. 


Any PARM operand on the EXEC statement is interpreted by the Terminal Monitor Program 
as the first line of input from the terminal. This input could be a command or the implicit 
execution of a command procedure containing setup commands for the TSO user. 


The EXEC statement is the only statement required in a LOGON procedure. 
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Optional Data Sets 


Data sets needed by a processing program such as a compiler or a system utility can be 
defined dynamically through the ALLOCATE command or through dynamic allocation. 


« Data sets the user wants for his TSO sessions should be placed in a LOGON procedure. 
This technique has three advantages: 


1. Allows volumes to be mounted. 


2. Provides recovery from an offline device condition. Messages tell the operator to 
VARY the device online. 


3. Saves repeated allocation and freeing of the same data set by successive commands in 
the same TSO session. 


Certain DD statements have special meaning and can be included in a LOGON procedure 
depending upon the installation’s needs. They are: 


SYSPROC — The SYSPROC DD statement defines the current command procedure library to 
the TSO EXEC command when the implicit form of the TSO EXEC command is used. The 
data set described by this DD statement must be partitioned with a record format of Vv, 
VB, F or FB. This statement can be defined in the LOGON procedure or can be 
dynamically allocated using the ALLOCATE command. 


sample listing (when used in LOGON procedure) 
//SYSPROC DD DSN=CLISY,PROC, LLB DIS P=SHR 


Sample terminal input (when used in ALLOCATE command) 


allocate da('clist.proc.lib') fi(sysproc) shr 


STEPLIB — A LOGON procedure can have a private step library defined by a STEPLIB DD 
statement. This library can contain command processors or a user-written TMP that the 
installation wants to make available to selected TSO users. (Note: SYS1.CMDLIB can be 
specified as a step library. However, it is not recommended; it would nullify the 
improvements that can be obtained by putting command processors in the LPA.) Most 
TSO users should not have STEPLIB in their LOGON procedure because of the extra 
search time required for each command and command procedure. 


SYSUADS — The ddname SYSUADS is used by the ACCOUNT facility to access the user 
attribute data set (UADS). SYSUADS can be allocated in the LOGON procedure or it can 
be dynamically allocated using the ALLOCATE command. Only those users authorized for 
the ACCOUNT command should have the SYSUADS DD statement included in their 
procedure. 
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Sample Procedure 


Figure 2 shows a sample listing of a LOGON cataloged procedure. The sample LOGON 
procedure can be useful to a programmer using Assembler F. The statements specify the TSO 
standard TMP for execution; define the library for the users EXEC commands, the work data 
sets for the assembler, the command procedure library, and the assembler macro library; and 
specify that SYSIN and SYSPRINT are to be directed to the user’s terminal. 


//BEPROC EXEC PGM=IKJEFTO1 ,DYNAMNBR=7 

//SYSUT1 DD DSN=§SYSUT1,UNIT=SYSDA, SPACE=(1700,(400,50) ) 
//SYSUT2 DD DSN=§SYSUT2, UNIT=SYSDA, SPACE=(1700,(400,50)) 
//SYSUT3 DD DSN=ESYSUT3, UNIT=SYSDA, SPACE=(1700,( 400,50) ) 
//SYSPROC DD DSN=CLIST. PROC. LIB, DISP=SHR 

//SYSLIB DD DSN=SYS1.MACLIB, DISP=SHR 

//SYSIN DD TERM=TS 

//SYSPRINT DD TERM=TS 


Figure 2. Sample Listing of LOGON Cataloged Procedure 


Space Allocation Using the Edit Access Method 


The following paragraphs explain the algorithms used in allocating EDIT’s utility work data set 
space when editing an existing data set or a new data set. These algorithms are used unless the 
EDIT utility work data sets are otherwise allocated by the installation. If a space parameter 
value is specified on an optional DD statement, the Edit Access Method space management 
will not be effective the first time it is used. 


When Editing an Existing Data Set — Two times the ((total number of characters contained 
within the data set plus additional requested records(*) divided by the average block size of 
4096) plus 2) gives you the initial space size in 4K blocks. Dividing the initial space size by 
two gives you the secondary space size. 


Example 


Known: 1. The data set contains 2000 records. 
2. Each record is 80 characters in length. 
3. The average block size is 4096. 


2x ((160,000 + 0 + 4096) + 2)=initial space (number of 4K blocks) 


Initial space + 2=secondary (space number of 4K blocks) 


Note: The EDIT subcommands MOVE and COPY request extra space whenever a second utility 
data set is used. 


When Editing a New Data Set — A new data set has four blocks with the average block size of 
4096 for the defaulted initial space and one half that amount for its secondary space. If it 
contains 80 - character records it has a total capacity of approximately 1300 records. 


SYSEDIT — SYSEDIT is a sample ddname for the & EDIT data set. When a DD Statement is 
included for & EDIT, dynamic allocation recognizes that the &EDIT data set is 
permanently allocated. Thus, the &EDIT data set allows an installation to control the 
allocation of Edit utility data sets, and to control the direct access space used for these 
data sets, however, it is used only the first time. 


SYSEDIT2 — SYSEDIT2 is a sample ddname for the EDIT2 data set. When a DD statement is 
included for & EDIT2, dynamic allocation recognizes that the & EDIT2 data set is 
permanently allocated. Thus, the & EDIT2 data set allows an installation to control the 
allocation of EDIT utility data sets and to control the direct access space used for these 
data sets, however, it is used only the first time. 
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Sample DD statements (when used in LOGON procedure) 


J {SYSEDLT DD DSN=6EDIT,UNIT=SYSDA,SPACE=( 1688,(50,20) ) 
//SYSEDIT2 DD DSN=&EDIT2,SPACE=( 4096,(20,10)),UNIT=SYSDA 


Creating, Converting, and Maintaining UADS and Broadcast Data Sets 
This section tells the system programmer how to: 


e create the UADS and broadcast data sets 
e convert the UADS and broadcast data sets to MVS format 
e maintain the UADS and broadcast data sets 


Introduction 


After system generation, the system programmer must ensure that UADS and broadcast data 
sets are available to the system. Both data sets have a specific format for MVS. The data sets 
can be created in MVS format or the format from previous releases. The LOGON processor can 
handle either old or new formats of the UADS, but the data set must be in MVS format in 
order to modify or add an entry. The broadcast data set must be in MVS format. After the 
UADS and broadcast data sets are established, authorized individuals can update them by 
adding, changing, or deleting entries. 


ACCOUNT Command and Its Subcommands 


The ACCOUNT command and its subcommands are used to create and update the entries in the 
UADS. Specifically, the ACCOUNT command can: 

e add new entries or more data to an existing entry (ADD subcommand) 

e delete entries or parts of entries (DELETE subcommand) 

e change data in an entry (CHANGE subcommand) 

e display the contents of an entry (LIST subcommand) 

e display the user identifications for all entries (LISTIDS subcommand) 


e build a new broadcast data set and synchronize it with an existing UADS (SYNC 
subcommand) 


e end operation of the command (END subcommand) 
e« find out how to use ACCOUNT subcommands (HELP subcommand) 


To use the ACCOUNT command under TSO, a terminal user must be authorized by the 
installation. The ACCOUNT command and its subcommands are explained in ''Part 2: 
Reference — TSO Commands" in this publication. 


To permit creating and maintaining the UADS and broadcast data sets from a batch job, 
MVS allows the terminal monitor program (TMP) to execute as a batch job that creates a TSO 
environment for ACCOUNT and its subcommands. Thus, the UADS and broadcast data sets can 
be created or maintained with or without having TSO active. 
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The UADS Reformatting Program — UADSREFM 


The SYS1.UADS data set does not have to be reformatted before using TSO. However, you J 
should be aware of the following points if you continue to use the old format: 


e The ACCOUNT command will cause entries to be added to SYS1.UADS in the new format. 


e The accounting fields are different in the new format. When the system resource manager 
updates accounting fields in SYS1.UADS, it assumes that SYS1.UADS exists in the new 
format. 


- A user cannot use the three parameters (MOUNT, DEST, PERFORM) of the ACCOUNT 
subcommands unless SYS1.UADS exists in the new format. 


Creating a new UADS by reformatting the old UADS before execution is accomplished by a 
batch job via the UADSREFM program, which operates under the TMP. In addition, the 
UADSREFM program can eliminate wasted space in the UADS caused by the periodic additions, 
deletions, and changes to UADS entries. The UADSREFM program reads a member from the old 
UADS, builds a logical copy of that member, eliminates any inefficient space, and places 
newly-formatted member in the new UADS. This process is repeated automatically for each 
member in the UADS. The UADSREFM program will not, however, reformat a users entry if the 
user is currently logged on the system; a message is written for every user that was not 
reformatted because the userid was in use. 


The UADSREFM program is invoked by executing the terminal monitor program and 
supplying a command, UADSREF™, in the SYSIN stream. Two DD statements are required by 
the UADSREFM program. A SYSUADN DD statement specifies the input UADS, which can be 
in MVS format or the format from previous releases. The SYSUADS DD statement specifies the 
output UADS, which will be in MVS format. 


Content and Structure of UADS ») 


The user attribute data set (UADS) is basically a list of terminal users who are authorized to 
use TSO. The UADS contains information about each of the users, and is used to regulate 
access to the system. There is an entry in the UADS for each terminal user. Each entry consists 
of the following information: 

-« A user identification. 

¢« One or more passwords, or a single null field, associated with the user identification. 

e One or more account numbers, or a single null field, associated with each password. 


e One or more procedure names associated with each account number. Each name 
identifies a procedure that may be invoked when the user enters the LOGON command. 


¢ The region size requirements for each procedure. 


e The name of the group of devices that the procedure will be permitted to use. Data sets 
located via the catalog are an exception. 


¢« The authority to use or a restriction against using the ACCOUNT command. 
¢ The authority to use or a reStriction against using the OPERATOR command. 


¢ The authority to use or a restriction against using the SUBMIT, STATUS, CANCEL, and 
OUTPUT commands. 


e Maximum region size allowed. 
¢ Installation-defined data. 


e The authority to specify or a restriction against specifying performance groups during 
LOGON processing. 


¢ The authority to specify or a restriction against specifying dynamic allocation requests for 


volume mounting. | ) 
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« A default destination for SYSOUT data sets (either the system output device or a remote 
work station). 


The organization of the information contained in the UADS is shown in Figure 3. Figure 4 
shows the simplest structure that an entry in the UADS can have, and Figure 5 shows a more 
complex structure. 


UADS Index 


The index points to each entry in the data set. 


(To other entries) 


The user identification identifies the entry and user 
attributes, and points to the password fields. 


(To other passwords) 


Password 


Each password field points to the account number fields 
that are associated with the password. 


(To other account numbers) 


Account 


Each account number field points to the procedure names 
that are associated with the account number. 


(To other procedure names) 


Procedure 


Associated with each procedure are region size 
requirements and device group. 





Figure 3. Organization of the UADS 
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Other attributes 


Figure 4. The Simplest Structure for a Typical UADS Entry 


UADS data set 





























User identification 


Password Password 


Account number Account number Account number 


Other attributes Other attributes Other attributes Other attributes Other attributes 


Figure 5. A Complex Structure for a Typical UADS Entry 
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Creating the UADS and Broadcast Data Sets From a Terminal 


Add to the procedure library a LOGON procedure named IKJACCNT. During system generation, 
one userid (IBMUSER) is copied into the newly-created UADS. IBMUSER is authorized to use 
one LOGON procedure, IKJACCNT. A sample IKJACCNT LOGON procedure follows: 


//IKJACCNT EXEC PGM=IKJEFTO1,DYNAMNBR=10 
//SYSUADS DD DSN=new uads created during sysgen 
//SYSLBC DD DSN=SYS1.BRODCAST created during sysgen 


Activate TCAM and initialize the TIOC (See ‘Initializing Time-sharing" in this publication.) 


Log on using the following command: 


logon ibmuser nonotices nomail 


The keywords NONOTICES and NOMAIL prevent the LOGON processor from accessing the 
broadcast data set before broadcast is formatted. Enter the ACCOUNT command and issue the 
SYNC subcommand to format a skeleton for broadcast data set. Issue ADD subcommands to 
add the new userids to both UADS and broadcast. 


Log on again with a new userid that has ACCOUNT authority. Enter the ACCOUNT 
command and issue the DELETE subcommand to delete the IBMUSER userid. 


Creating the UADS and Broadcast Data Sets With a Batch Job 


While running the newly-generated system, execute the ACCOUNT facility as a batch job. Use 
the SYNC subcommand of ACCOUNT to format a skeleton for the broadcast data set. Then, as 
each userid is added to UADS via the ADD subcommand of ACCOUNT, a corresponding entry is 
made in the broadcast data set. IBMUSER, a userid with ACCOUNT authority provided during 
system generation, can be used to create a new UADS. Because a new UADS has been created, 
IBMUSER should be deleted. Figure 6 is a sample listing showing the creation of UADS and 
broadcast with a batch job. An explanation of this JCL can be found under "Executing the 
TMP as a Batch Job". 


//jobname JOB job card parameters 
EXEG PGM=IKJEFTO1 
//SYSPRINT DD SYSOUT=A 
//SYSUADS DD DSN=uads created during sysgen 
//BRODCAST DD DSN=SYS1.BRODCAST ,DISP=SHR 
//SYSIN DD * 
ACCOUNT 
SYNC 


ADD new userid 


DELETE. ¢( TBMUSER J 
END 


j * 
Figure 6. A Sample Listing, Showing the Creation of UADS and Broadcast With a Batch Job 


Converting the UADS and Broadcast Data Sets 


While running the newly-generated system, execute the ACCOUNT facility with a batch job. 
Use the UADSREFM program to create an MVS UADS containing the userids from the old 
format UADS. Use the SYNC subcommand of ACCOUNT to format an MVS broadcast data set 
with an entry for each userid in the UADS. IBMUSER, a userid with ACCOUNT authority 
provided during system generation, can be used to create a new UADS. Because a new UADS 
has been created, IBMUSER should be deleted. Figure 7 is a sample listing showing the 
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conversion of UADS and broadcast. An explanation of this JCL can be found under ''Executing 


the TMP as a Batch Job". ) 


//jobname JOB Job statement parameters 
EXEC PGM=IKJEFTO1 
//SYSPRINT J BD SYSOUT=A 
//SYSUADN DD DSN=old format uads 
| //SYSUADS DD DSN=MVS format uads 
/ /NEWBROD DD DSN=SYS1.BRODCAST ,DISP=SHR 
//SYSIN DD * 
UADSREFM 
ACCOUNT 
SYNC 
DELETE ( LBMUSER ) ‘ 
END 
/* 


Figure 7. A Sample Listing, Showing the Conversion of UADS and Broadcast 


Maintaining the UADS and Broadcast Data Sets From a Terminal 


To maintain UADS and broadcast from a terminal, a terminal user must log on with a userid 
that is authorized to enter the ACCOUNT command. The terminal user must also ensure that 
the UADS to be updated is allocated to the SYSUADS DD statement (either in a LOGON 
procedure or via an ALLOCATE command). The actual changes to UADS are done by issuing 
the ACCOUNT command followed by its subcommands. 


Executing the TMP as a Batch Job 


so that the TSO service routines ACCOUNT and its subcommands, PROFILE and the Access 
Method Services utilities can function. Input for a GETLINE is obtained from the data set 
defined by the SYSIN DD statement. The TMP issues the STACK macro instruction to put the 
SYSIN data set on the input stack. Messages issued via PUTLINE are written to the data set 
defined by the SYSPRINT DD statement. 


The terminal monitor program (TMP) if invoked in the background, creates a TSO environment ) 


Multi-level messages are automatically written out as if a question mark(?) had been 
entered. The commands that are read from SYSIN are logged on SYSPRINT. Because of this, the 
commands and subcommands can be entered via SYSIN. Each command must begin on a 
separate card. Continuation is indicated according to ‘Continuation Lines" elsewhere in this 
book. 


No prompting is done because the TMP sets options as if the following PROFILE command 
had been issued: 
profile noprompt noprefix noline nochar 
Since "noprefix'’ is defaulted, an unqualified data set name will not have a userid prefixed 


to it. If you would like to have a userid prefixed to the data-set-names specified on the Access 
Method Services utilities include the command; 


profile prefix(userid) 
at the beginning of the SYSIN stream. 
The JCL used to run the TMP in a batch job is the: 


1. EXEC statement with PGM=IKJEFTOI should have a DYNAMNBR parameter if ACCOUNT 
will dynamically allocate SYSI.LBRODCAST or SYSI.HELP data sets (This is only for HELP 
subcommands). Optional for this statement is the PARM operand, which is interpreted as 
the first line of input from SYSIN. J 
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2. SYSPRINT DD statement for commands and subcommands executed, plus messages. 
3. SYSIN DD statement for data set containing commands and subcommands. 


Note: The SYSIN and SYSPRINT DD statements may refer to a sequential or partitioned data 
set. If the data set is partitioned, the member name must be specified on the DD card as 
DSN=pdsname(membername). The SYSIN data set cannot be a concatenated data set. 


Maintaining the UADS and Broadcast Data Sets with a Batch Job 


To maintain the UADS broadcast data sets, use the JCL described above. In addition, three 
other DD statements may be used: 


1. SYSUADS DD statement specifying the UADS to be accessed by ACCOUNT and 
UADSREFM. 


2. SYSUADN DD statement specifying a UADS to be accessed by UADSREFM. 


3. An optional DD statement specifying the broadcast data set to be accessed by 
ACCOUNT. If a DD statement is not specified, data set SYS1.LBRODCAST must be 
cataloged. 


Note: Any job that invokes the TMP in a batch job is given the authorization to execute the 
ACCOUNT command. For security, the UADS should be password protected or a JCL exit 
should be written to limit access to the background TMP. 


Initializing ‘Time-Sharing 


Before a terminal user can log on, TCAM must be active in the system and the terminal 1/0 
controller (TIOC) must be initialized. The initialization of TIOC completes the initialization for 
the time-sharing subsystem and allows TCAM to accept LOGON commands and pass them to 
TIOC for processing. 


To start TCAM the system operator must enter the START command as follows: START 
TCAM, (where TCAM is the name of a procedure that executes the TCAM MCP). 


After TCAM has been started the system operator must enter the MODIFY command to 
activate TIOC as a subtask of TCAM: MODIFY TCAM,TS=START. 


If a parmlib member other than IKJPRMO00 is to be used for TIOC parameters, the member 
name should be included on the MODIFY command. For example: 
modify tcam,ts=start,ikjprm01 
For additional information pertaining to the section on IKJPRMOO0, see System Programming 


Library: Initialization and Tuning Guide. 


To terminate all time-sharing users’ connections with the system, the system operator must 
issue the MODIFY command as follows: MODIFY TCAM,TS=STOP. 


For more information on START and MODIFY commands, see Operator’s Library: OS/VS 
TCAM, GC30-2037. 


Writing Installation Exits for the SUBMIT Command 


The TSO SUBMIT command allows a terminal user to initiate a batch job. The SUBMIT 
command processor writes the user-specified data set(s), consisting of JCL statements and 
input data, into a job entry subsystem internal reader. Through an exit routine, an installation 
can approve, reject, or modify the JCL statements being submitted. 
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When the first JOB statement is read (or generated), the SUBMIT command processor 
invokes the exit routine. As a default, only JOB statements (and continuations) are presented 
to the exit routine. The routine can dynamically indicate additional types of JCL statements = 
that it wishes to inspect as the statements are read from the input data set(s). The routine can 
delete or change the current statement and can generate continuation and/or new statements 
to follow the current one. The routine can also send a message to the user’s terminal and can 
request a response. In addition, the exit routine can verify jobname and userid, and can cancel 
a SUBMIT request. 


IBM-Supplied Exit Routine 


If an installation-written exit routine is not supplied, an IBM-supplied exit receives control. The 
IBM-supplied exit does not perform JCL checking. It is entered once for each SUBMIT command 
(JOB statement); it turns off all switches that cause it to receive control, and sets the return 
code to zero. 


Installation-Written Exit Routine 


The installation-written SUBMIT exit routine must be linkage-edited in SYS1.LINKLIB as an 
independent module named IKJEFF10, with reusable, reenterable, and refreshable linkage-edit 
characteristics. The SUBMIT command processor issues LOAD and CALL macro instructions for 
the exit routine and passes control in key 1 (scheduler key) and in supervisor state for 
protection purposes. (A terminal user cannot have a revised version of the exit routine in a 
LOGON procedure’s step library and cannot pre-load a revised version using the TEST 
command because only the system link list is used for the LOAD.) The exit routine must 
follow standard linkage conventions. 


In the course of SUBMIT command processing, the exit routine may be passed each JCL 
Statement that is submitted, except for delimiter statements. By setting return codes and 2 
switches and by passing parameters to the SUBMIT processor, the routine can control the 
statements passed to it. The return codes and switches also determine subsequent calls to the 
exit routine. The return codes (to be set in register 15 before the exit routine returns control 
to the SUBMIT processor) are: 


Q Continue — (that is, process the current statement and read the next). 


4 Reinvoke the exit routine to obtain another statement — that is, process the current 
Statement and invoke the exit routine again so that it can insert a statement. 


8 Display message 1KJ562831 (message text is supplied by the exit routine) at the terminal 
and invoke the exit routine. The exit routine must obtain the message text area and may 
free it when reentered. 


12 Display prompting message IKJ56280A (message text is supplied by the exit routine) at 
the terminal, obtain a response, and invoke the exit routine. (If the user has specified 
NOPROMPT on a PROFILE command or uses a command procedure without the PROMPT 
option in effect, this will cause the SUBMIT processor to issue a message and terminate 
the SUBMIT command.) The SUBMIT command processor must obtain and free the reply 
text area. The exit routine must obtain the message text area and may free it when 
reentered. 


16 Terminate the SUBMIT command. (The exit routine should first use return code 8 to 
issue a message to the user.) 


Undefined return codes cause the SUBMIT processor to issue an error message and 
terminate. 
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Upon entry, register 1 contains the address of a pointer to an eight-word parameter list. The 
system programmer can issue the IKJEFFIE mapping macro instruction to format this parameter 
list and to assign equates for return codes by coding IKJEFFIE IETYPE=SUBMIT. As a result, 
two assembler DSECTs named IEDSECTD and IESUBCTD are created. (See OS/VS2 Data Areas, 
for the format of each DSECT.) After establishing addressability with each DSECT, the system 
programmer can refer to the DSECT fields by name. The contents of the parameter list are: 


Word 1 
Address of the current statement. If zero, it indicates a request for the exit routine to supply 
the next JCL statement (return code from previous call of the exit routine was 4). To delete 
the current statement, the exit routine must set this word to zero. The exit routine can also 
change the statement and issue return code Q or 4 to have the statement processed. 


Word 2 
Address of a message to be displayed on the user’s terminal, supplied in conjunction with 
return code 8 or 12. If nonzero on entry, the return code from the previous call to the exit 
routine was 8 or 12. The exit routine must obtain the message buffer and may free it when 
reentered. If word 2 is zero, no message is present (the previous return code was Q or 4, or 
this is the first call). The format of the message is 'LLtext'', where LL is a two-byte field 
containing the length of the message text area (including the LL field). The maximum text 
length is 246 bytes. 


Word 3 
Address of the response from the terminal user if the exit routine’s previous return code was 
12. When this field is nonzero after calling the exit routine, the SUBMIT command processor 
frees the buffer. The format of the response is 'LLtext'', where LL is a two-byte field 
containing the length of the reply (including the LL field). 


Word 4 
Address of userid. The userid is eight characters left-justified, padded with blanks. 


Word 5 
Address of the control switches, which are contained in a fullword. Byte 0 specifies under 
what conditions the SUBMIT command processor will call the exit routine: 


Byte Bit Meaning 
0 0 Call exit routine for JOB card 
| EXEC 
2 DD 
3 Command or PROC or PEND 
4 Null 
5 /*X in card columns 1-3 (JES2 control card - with /* in columns | and 2 and a 
nonblank character in column 3) 
6 //* in columns 1-3 (comment card) 
7 Reserved 


By default, the SUBMIT command processor enters the exit routine for JOB statements only. 
The exit routine can change the setting of these bits to control when it will be entered. For 
example, the exit routine can set bit 3 to request control when operator commands are 
found in the submitted JCL. 


Byte 1 Gif nonzero) indicates the card column where the operand field begins. For example, 
if the operand field begins in column 16, byte 1 contains hexadecimal 10. 
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Bytes 2 and 3 identify the current statement to the exit routine. 


Byte Bit Meaning 
2 () JOB statement 
| EXEC 
2 DD 
3 Command or PROC or PEND 
4 Null 
5 Operand to be continued 
6 Statement to be continued 
iz Statement is a continuation 
3 0 /*X in columns {-3 (JES2 control card with /* in columns | and 2 and a nonblank 


character tn column 3) 
| //* in columns 1-3 (comment card) 


If bit 5 in byte 2 is on, bit 6 also must be on, but bit 6 can be on while bit 5 is off. If bit 3 
is on, the current JCL statement has // in columns | and 2 but has not been recognized as 
a JOB, EXEC, or DD statement. The SUBMIT command processor assumes that the // 
statement is an operator command entered into the input stream. 


The exit routine is not passed the preceding JCL statements if they are in a DD DATA (or 
DD *, for /*X cards) input data stream. 


Word 6 
For the exit routine’s use. The first time the SUBMIT command processor calls the routine, 
word 6 is initialized to zeros. The routine can use the word for counters or switches. The 
value is not changed between calls. 


Word 7 
Address of reconstructed LOGON job accounting information for the user. The SUBMIT 
command processor inserts this information into generated JOB statements. 


Word 8 
Address of a halfword that contains the length of the job accounting information. 


Note: Normally an installation exit routine issues a message by setting a return code, putting 
a message address in word 2 of the parameter list, and returning control to SUBMIT command 
processor. If the exit routine wants to issue a message with a second level via PUTLINE or 
PUTGET, it must issue a MODESET macro instruction to change to key 0. After issuing the 
message, the routine must issue MODESET again to change back to key 1. 
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Writing Installation Exits for the OUTPUT, STATUS, and CANCEL 
Commands 


An installation-written exit routine can control the conditions under which OUTPUT, STATUS, 
and CANCEL commands will be allowed. The exit routine can restrict a terminal user from 
obtaining status for a job, from canceling another terminal user’s job, or from receiving the 
output of another terminal user’s job. The exit routine can restrict a terminal user from 
directing a job’s output to a specific data set or from changing a job’s output class. Also, the 
exit routine can send a message to the user’s terminal and can request a response. In 
determining whether to allow one of the commands to execute, the exit routine can verify the 
userid, jobname, and jobid. The exit routine is not entered for a STATUS command with no 
operands. 


IBM-Supplied Exit Routine 


If an installation-written exit routine is not supplied, an IBM-supplied exit (common to all three 
command processors) receives control. The IBM-supplied exit routine allows a terminal user to 
obtain the status of any job in the system. However, it restricts a terminal user from canceling 
any jobs other than his own. It also restricts a terminal user from obtaining the output of any 
jobs other than his own. The IBM-supplied exit routine checks the userid specified on the 
LOGON command against the jobname or jobnames entered on the CANCEL or OUTPUT 
command. (Jobname must equal the userid plus at least one character for CANCEL, and must 
be the userid or must start with the userid for OUTPUT.) If the terminal user entered an invalid 
jobname, the IBM-supplied exit routine sets up an error message to be issued by the 
appropriate command processor and tells the command processor via return code to ignore the 
CANCEL or OUTPUT request for that jobname. If any other jobnames are listed on the same 
command, the IBM-supplied exit routine processes them in order. 


Installation-Written Exit Routine 


The installation-written exit routine for OUTPUT, STATUS, and CANCEL commands is also 
common to all three command processors. The exit routine determines via a command code (in 
word 7 of the parameter list) which command processor is invoking it. The installation-written 
routine must be linkage-edited in SYS1.LINKLIB as an independent module named IKJEFFS3, 
with reusable, reenterable, and refreshable linkage-edit characteristics. All three command 
processors issue LOAD and CALL macro instructions for the exit routine and pass control in 
key 1 (scheduler key) and in supervisor state for protection purposes. (A terminal user cannot 
have a revised version of the exit routine in a LOGON procedure’s step library and cannot 
pre-load a revised version using the TEST command because only the system link list is used 
for the LOAD.) The exit routine must follow standard linkage conventions. 


After determining the action it wishes to take, the exit routine indicates the action to the 
appropriate command processor by setting the return code in register 15. The return codes are: 


Q Valid jobname; get next jobname, and continue processing. 


4 Display message IKJ56208A (message text is supplied by the exit routine), get response, 
and call the exit routine again with the same jobname. If the terminal user has specified 
NOPROMPT on a PROFILE command or uses a command procedure without the PROMPT 
option in effect, the command processor terminates and issues a message to the terminal. 


8 Display message IKJ562081 (message text is supplied by the exit routine) and call the exit 
routine again with the same jobname. The IBM-supplied exit routine produces the 
message JOB jobname REJECTED - JOBNAME MUST BE YOUR USERID PLUS AT LEAST 
ONE CHARACTER. 
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12 Invalid jobname: cancel request for this job, then continue checking any other jobname 
on the command. The exit routine should first use return code & to issue a message. 


16 Terminate the CANCEL, OUTPUT, or STATUS command. The exit routine should first 
issue an error message, using return code &. 


Undefined return codes cause the command processor to issue an error message and 
terminate. 


Upon entry to the installation-written exit routine, register | contains the address of a 
ten-word parameter list. The system programmer can issue the IKJEFFIE mapping macro 
instruction to format this parameter list. For CANCEL or STATUS, issue: IKJEFFIE 
IETYPE=CANST. As a result, an assembler DSECT named IEDSECTD is created. For OUTPUT, 
issue: IKJEFFIE IETYPE=OUTPUT. As a result, two assembler DSECTs named IEDSECTD and 
IEOUTPLD are created. (See OS/VS2 Data Areas, for the format of each DSECT.) After 
establishing addressability with each DSECT, the system programmer can refer to the DSECT 
fields by name. 


The contents of the parameter list are: 


Word 1 
Contains the address of the jobname. 


Word 2 
Contains the address of a halfword that contains the length of the jobname. 


Word 3 
Contains the address of the userid. 


Word 4 
Contains the address of one byte that contains the length of the userid. 


Word 5 
Contains the address of a message to be displayed on the terminal, supplied by the exit 
routine when the routine specifies return code 4 or 8. The format of a message is ''LLtext’’ 
where LL is a two-byte field containing the length of the entire message (including the LL 
field). The maximum text length is 246 bytes. The exit routine must obtain and may free 
the message text area. 


Word 6 
Contains the address of a response from the terminal user if the exit routine’s previous 
return code was 4. The format of the response is ''LLtext'’ where LL is a two-byte field 
containing the length of the entire reply (including the LL field). The caller of the exit 
routine obtains and frees the reply text area. 


Word 7 
Contains the address of the one-byte caller command code. The command codes are: 


Q STATUS command 
4. CANCEL command 
8 OUTPUT command 
Word 8 
Contains the address of the jobid, if jobid was specified on the command. This word is zero 
if jobid was not specified. 


Word 9 
Contains the address of a halfword that contains the jobid length. The length field is zero if 
jobid was not specified. 
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Word 10 
(for OUTPUT command) contains the address of a list of pointers and bits reflecting the 
syntax entered by the terminal user. The total length of this list is five fullwords, with the 
following contents: 


Word | — pointer to the first class parse descriptor entry (PDE) on the chain of PDEs. Zero 
if class was not specified on OUTPUT command. 


Word 2 — pointer to the print-data-set-name PDE. Zero if not entered. 
Word 3 — pointer to the new class PDE. Zero if not entered. 
Word 4 — pointer to the destination PDE. Zero if not entered. 


Word 5 — only the first one and one-half bytes (high-order) are used to reflect the 
user-entered syntax as follows: 
‘8000° PAUSE (lf off, assume NOPAUSE or not applicable) 
“4000 HOLD (lf off, assume NOHOLD or not applicable) 
‘2000° HERE 
*1000° BEGIN 
‘0800’ NEXT 
‘0400 DELETE 
‘0200 PRINT 
‘0100 NEWCLASS 
‘0080 KEEP (If off, assume NOKEEP or not applicable) 
0040" DEST 
‘0020 Reserved 
‘0010 Reserved 


The high-order bit of word 10 must be on to indicate the end of the parameter list. 


Writing a LOGON Pre-prompt Exit Routine 


The LOGON command initiates a terminal session by supplying the system with certain basic 
information: userid, password, account number, procedure name, region size, and performance 
group. An installation can write an exit routine to specify these values for the LOGON 
command and thereby customize the LOGON procedure for that installation’s terminal users. 
The exit routine can supply system and user attributes for the protected step control block 
(PSCB), generic group name, performance group, and default SYSOUT destination. It can also 
provide JCL statements to be used instead of the JOB and EXEC statements constructed by the 
LOGON processor. 


Installation Exit Routine Logic 


The installation-written exit routine must be linkage-edited with load module IKJEFLD into 
SYS1.LPALIB. When the LOGON processor receives a LOGON command from a terminal user 
and before it opens the UADS, it passes control to the exit routine as a problem program. The 
exit routine can use the 1/O service routines through assembler macro instructions (STACK. 
PUTLINE, GETLINE, and PUTGET). The macros require the addresses of the ECT and UPT, two 
of the parameters passed from the LOGON processor. 


When the exit routine receives control, register 13 points to a register save area. Register | 
points to a list of addresses, one address for each parameter. (See Figure 8 for the format of 
the address list. The parameters can be given any name; their meaning is determined by the 
order of appearance. The names used in the following explanation are for illustrative purposes 
only.) Four address-list entries point directly to the data area. Each of the other entries points 
to a two-word descriptor: the address of the data area (four bytes), the maximum length of the 
data area (two bytes), and the current length of the data actually in the data area (two bytes). 
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Register 1 


Address List Descriptors Data Area 


4 Control Switches Control Switches 
A Control Switch Desc. 32 32 


Input Buffer 
Input Buffer Desc. p ae Input Buffer 


Userid Desc. } Userid Userid 


Password Desc. 4 Password Password 


Account Number Desc, A= Account Number Account Number 


A Procedure Name Desc. Procedure Name Procedure Name 
Region Size Region Size 
JCL Desc. JCL Cards 10 JCL Card Images 


Reserved 


System Attribute Desc. 


A System Attributes System Attrib. Bits } | 


User Attribute Desc. A User Attributes User Attrib. Bits 


Generic Unit Desc. A Generic Unit Generic Unit 


>_> 


UPT Desc. A UPT Image UPT Image 
128 


ECT Desc. ECT (Actual) 


Cancel ECB CHCECR 


Last Step Completion Code LWARTCD 


Performance Group Performance Value 


A Default Sysout Dest. A Dest. Userid Dest. Userid 





Figure 8. LOGON Pre-prompt Parameters 


The exit routine must move the proper data to the data area, update the current length | 
field, and turn on the appropriate control switch bit, if it exists. The control switch bit ) 
indicates to the LOGON Processor that the exit routine has passed the corresponding parameter 
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The exit routine must move the proper data to the data area, update the current length 
field, and turn on the appropriate control switch bit, if it exists. The control switch bit 
indicates to the LOGON processor that the exit routine has passed the corresponding parameter 
in the data area. For example, if the JCL control switch bit is set to one, the JCL data area 
must be supplied. 


The data address field, the maximum length field, and the addresses in the address list must 
not be altered. These fields are checked by the LOGON processor and must be the same upon 
return as they were upon entry. If they are altered, an appropriate error message is issued and 
the LOGON processor terminates. 


Parameter Descriptions 


Control Switches: The control switch bits set by IKJEFLD indicate to the LOGON processor 
that the exit routine has passed the corresponding parameter in the data area or indicate an 
action to be taken by the LOGON processor. The control switch bits set by the LOGON 
processor indicate to the exit routine that certain system conditions exist. The bit configuration 
is as follows: 


Byte Bit Field Name 
0 0 Userid ENQ fail 
I Reserved 
2 Resource failure 
3 Disconnect 
4 Don't prompt 
3 No UADS 
6 JCL 
7 Reserved 
I 0 System attributes 
| User attributes 
2 Generic group 
3 User profile table (UPT) 
4 Don’t ENQ userid 
5 Destination 
6 Abend 


Note: If don’t-prompt bit is set to one, the values for userid, password, account, procedure, 
region size, and performance group data areas must be supplied. If no-UADS bit is set to one 
also, then system attributes, user attributes, generic group, and UPT data areas must be 
supplied. 


Userid ENQ fail 


Set by the LOGON processor to tell IKJEFLD that the ENQ on the userid was unsuccessful, 
implying that the userid is in use. 


Reserved 
This bit is reserved. 


Resource Failure 


Set by the LOGON processor to tell IKJEFLD that the LOGON processor was unable to 
obtain a resource other than the userid. 


Disconnect 


Set by IKJEFLD to tell the LOGON processor to terminate the session. The LOGON processor 
sends no further message to the terminal. 


Don’t Prompt 
Set by IKJEFLD to tell the LOGON processor that IKJEFLD has supplied userid, password, 


procedure name, account number, region size, and performance group. The user cannot be 
prompted. 
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No UADS 


Set by IKJEFLD to tell the LOGON processor not to look at the UADS to verify the userid, 
account number, etc. 


JCL 
Set by IKJEFLD to tell the LOGON processor that IKJEFLD has supplied a maximum of ten 
80-byte JCL statements in standard JCL format. 


Reserved 
This bit is reserved. 


System Attributes 


Set by IKJEFLD to tell the LOGON processor that IKJEFLD has supplied the system attribute 
bits. 


User attributes 


Set by IKJEFLD to tell the LOGON processor that IKJEFLD has supplied the user attribute 
bits. 


Generic group 


Set by IKJEFLD to tell the LOGON processor that IKJEFLD has supplied a generic group 
name. 


UPT 
Set by IKJEFLD to tell the LOGON processor that IKJEFLD has supplied the UPT. 


Don’t ENQ 
Set by IKJEFLD to tell the LOGON processor not to ENQ on the userid, implying that more 
than one user can log on with the same userid. 


Destination 
Set by IKJEFLD to tell the LOGON processor that IKJEFLD has supplied the default SYSOUT 
destination. 


Abend 


Set by LOGON processor’s ESTAI retry routine to indicate to IKJEFLD that an abend has 
occurred and the LOGON processor is retrying One more time. 


Input buffer: Contains the input line entered from the terminal. It is obtained by LOGON 
processor and passed to IKJEFLD. 


Userid: Passes a userid to the LOGON processor. The don’t-prompt bit must be set to one in 
order for LOGON processor to accept the userid. 


Password: Returns a password to the LOGON processor. The don’t-prompt bit must be set to 
one in order for the LOGON processor to accept the password. 


Account: Passes an accounting string to the LOGON processor. The don’t-prompt bit must be 
set to one in order for LOGON processor to accept the accounting string. 


Procedure: Passes to LOGON processor the name of a cataloged procedure containing JCL to 
define the resources needed by the terminal job. The don’t-prompt bit must be set to one in 
order for the LOGON processor to accept the procedure name. 


Region size: Passes to the LOGON processor a region size for the terminal job. The 
don’t-prompt bit must be set to one in order for the LOGON processor to accept the region 
Size. 


30 OS/VS2 System Programming Library: TSO (VS2 Release 3) 


JCL: Provides JCL statements that define terminal job resources. This JCL is used instead of 
the JOB and EXEC statements constructed by the LOGON processor. The JCL field is 800 bytes 
(maximum) in length; therefore, ten card images (maximum) can be passed to the LOGON 
processor. The LOGON processor expects the JCL data to be in card image - each 80 bytes of 
the area should contain a full 80-byte JCL statement in standard format. Updating the current 
length field tells the LOGON processor the number of cards being passed (80 x N cards). The 
JCL bit must be set to one in order for LOGON processor to accept the JCL supplied. 


Reserved: This parameter is reserved. 


System attributes: Returns a value to the LOGON processor for the PSCBATRI string in the 
PSCB. Either the system-attributes bit or don’t-prompt and no-UADS bits must be set to one. 
See OS/VS2 Data Areas, for a description of the PSCB. 


User attributes: Returns a value to the LOGON processor for the PSCBATR2 string in the PSCB. 
Either the user-attributes bit or the don’t-prompt and no-UADS bits must be set to one. See 
OS/VS2 Data Areas, for a description of the PSCB. 


Generic group: Returns a value to the LOGON processor for the PSCBGPNM field of the PSCB. 
The group name is initialized from the UADS by the LOGON processor unless the generic-group 
bit or the don’t-prompt and no-UADS bits are set to one by IKJEFLD. See OS/VS2 Data Areas, 
for a description of the PSCB. 


UPT: The LOGON processor passes a UPT containing binary zeros to IKJEFLD. This UPT can 
be updated and returned to the LOGON processor if the UPT bit or the don’t-prompt and 
no-UADS bits are set to one. See OS/VS2 Data Areas, for a description of the UPT. 


ECT: Passed to IKJEFLD, may be modified by IKJEFLD, and will be used by the LOGON 
processor. This is the actual environment control table ECT built by LOGON processor. 
IKJEFLD need not set any bit to tell LOGON processor to accept the ECT. 


Cancel ECB: The ECB used by the system for cancel processing. This ECB can be read but not 
altered by IKJEFLD. If cancel ECB is nonzero, LOGON processor terminates the present session. 


Last step completion: During a re-LOGON, this is a full word containing the completion code 
for the userid that was just logged off. 


Performance group: Passes to the LOGON processor a number that associates terminal user 
interactions with one of several performance groups. For further information concerning 
performance, refer to the OS/VS2 System Programming Library: Initialization and Tuning Guide. 


Default SYSOUT destination: Default SYSOUT destination parameter returns to the LOGON 
processor the default SYSOUT destination for a userid. 
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Sample LOGON Pre-prompt Exit Routine 


A sample listing of a LOGON pre-prompt exit is shown in Figure 9. Besides performing 
housekeeping functions and satisfying linkage conventions, the exit routine supplies two JCL 
Statements (JOB and EXEC) and updates the current length field to indicate that the data area 
contains 160 bytes of data. The exit routine also sets the JCL control switch bit to one to tell 
the LOGON Processor that the JCL parameter is being passed. 





CSECe ITKJEFLD 
Q 


RO EQU 
RI EQU 1 
R5 EQU 5 
R6 EQU 6 
R7 EQU 7 
RC EQU 12 
RD EQU 13 
RE EQU 14 
RE EQU 15 
USING *,RF 
STM  RE,RC,12(RD) SAVE REGISTERS 
L R7,28(R1) INITIALIZE REG SEVEN TO 
io R6,0(R7) POINT TO JCL DATA AREA 
MVC 0(80,R6),OURJCL MOVE JOB CARD 
MVC 80(80,R6),OUREXEC MOVE EXEC CARD 
MVC 6(2,R7),OURCNT UPDATE CURRENT LENGTH 
i, R5,0(R1) INITIALIZE REG FIVE TO 
L R5,0(R5) POINT TO CONTROL SWITCHES 
OI O(R5),xX'02' TURN ON JCL SWITCH 
LM RE,RC,12(RD) RESTORE REGISTERS 
BR 14 EXIT 
OURTCL, <DC C'//IBMUSER JOB (D72598,9,OPR),1BM,MSGLEVEL=1,' 
De C'MSGCLASS=M, TIME=1439 
OUREXEC DC c'//ST1 EXEC IKJACCNT 
De ce 
OURCNT DC H'160' UPDATED CURRENT LENGTH 
END 


Figure 9. Sample Listing of a LOGON Pre-prompt Exit 


Writing Installation Exits for the RENUM, MOVE and COPY 
Subcommands of EDIT 


The RENUM subcommand of the EDIT command assigns a line number to each record in a 
data set that does not have line numbers; it also renumbers each record in a data set that has 
line numbers. The MOVE subcommand of the EDIT command moves lines in a data set from 
one location to another, renumbering the moved lines as necessary. The COPY subcommand 
of EDIT command copies lines in a data set, renumbering the copied lines as necessary. 


However, the RENUM, MOVE and COPY subcommand processors cannot handle certain 
data set types (for example, VSBASIC data sets) that can have by embedded line references 
(using a line number as a destination or statement "label" in a statement that passes control, 
such as GOTO statements). Thus, an installation may want an exit routine that renumbers, 
moves, records and copies records in an in-storage data set, adjusting line references as 
necessary. An exit routine can also be used to flag a statement (for example, by adding a 
comment at the end of the statement) or to use a nonstandard numbering scheme. 


IBM-Supplied Exit Routine — VSBASIC Data Set Type 


If an installation-written exit routine is not supplied for the VSBASIC program product, an 
IBM-supplied exit routine (supplied with the VSBASIC program product) receives control. The 
MOVE and COPY functions are not supported by the IBM-supplied exit. For a RENUM 
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request, the exit routine renumbers the data set’s records and scans the data set for statements 
-that contain line references. When it encounters a line reference, the routine updates the 
reference to reflect the revised line number. Upon successful completion, the exit routine 
passes return code 0 to the subcommand processor. If it fails, the exit routine issues a message 
to the terminal user, sets the return code to 8, and returns control to the subcommand 
processor. The name of the IBM-supplied exit routine defaults to ICDQRNME during system 
generation. 


Installation-Written Exit Routine 


The RENUM, MOVE and COPY subcommand processors issue LOAD and CALL macro 
instructions for the exit routine, which can reside in a step library, in the LPA library, or in any 
data set in LNKLSTxx. (The exit routine’s name must previously have been specified on the 
EDIT macro instruction during system generation as the DATEXIT value for the applicable data 
set type(s). The default is to only have a DATEXIT for the VSBASIC data set type.) The exit 
routine must follow standard linkage conventions. A work area is not passed to the exit 
routine; it must obtain and release any storage needed. If storage is obtained, it must be in 
subpool 1. The routine has the use of all TSO service routines in its processing. 


The exit routine receives an in-storage data set as input. After processing the data set, the 
routine must return the data set to the subcommand processor. The subcommand processor 
copies the data set to a new utility data set to complete the operation. 


The routine is expected to periodically check the EDIT command attention ECB for function 
interruption. When an interrupt occurs, the exit routine must return control to the 
subcommand processor with return code O, after releasing all resources it has obtained. 


Upon any completion, the exit routine must release any resources it has obtained. On 
successful completion, the routine must return a pointer to the updated in-storage data set and 
its length, if applicable. It must also update the current line pointer (in the subcommand 
interface area). The exit routine indicates success or failure by the return code that it sets in 
register 15: 

Q successful completion or attention interrupt 

4 requests processing as if the exit routine were not available 


8 function not performed, message sent to the terminal user 


Upon entry, register 1 contains the address of a parameter list: 
Offset (Hex) Length Contents 


0 4 UPT address 
4 4 ECT address 
8 4 EDIT attention ECB address 
C 1 Flags: 
Bit 0 0 - Records have standard line numbers 


1 - Records do not have standard line numbers 
Bit | 0 - Not RENUM function 
1 - RENUM function 
Bit 2 0 - Not MOVE function 
1 - MOVE function 
Bit 3 0 - Not COPY function 
1 - COPY function 
Bit 4 0 - Normal line range specification 
1 -’* COUNT range notation 
Bit 5 0 - Fixed length records 
1 - Variable length records 
3. Address (in storage) of data set 
10 4 Address of subcommand interface 
14 4 Address of data attribute parameters 
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The in-storage data set contains all records in the current EDIT utility data set, in the format 
prescribed by the RECFM applying to the EDIT input data set. All variable record lengths are 
described by the standard header word (LL/00). Fixed record lengths are described by the data 
attribute parameters. All records by the data set are back-to-back and are contained in a single 
area of virtual storage, assigned from subpool 1. 


The subcommand interface area, which contains all values in binary, consists of: 
RENUM format: 
Offset (Hex) Length Contents 


0 4 Line number position 

4 4 Length of line number 

8 4 First line to be renumbered (0 indicates first line of data set) 

C 4 Last line to be renumbered (X‘7FFFFFFF requests renumbering through end of 
data set) 

10 4 Line number to be assigned to the first renumbered line 

14 4 Increment to be used 

18 4 Address of current line reference (updated by exit routine before it returns control 


to the RENUM subcommand processor) 
MOVE/COPY format: 
Offset (Hex) Length Contents 


0 4 Line number position 

4 4 Length of line number 

8 4 First line of MOVE/COPY range 
(O indicates first line in data set) 

Cc 4 Last line of MOVE/COPY range 


(Bit 4 of flags = 1) 
4 Line number of line preceding insertion point 
14 4 Increment to be used 
4 Current line pointer 


The data attribute parameters consist of a two-word list: 
Q 4 Logical record length (in bytes) 
4 4 Length of the data set (in bytes) 


Data Set Types and Syntax Checking 
This section tells the system programmer how to: 


e define a data set type 
* write a syntax checker for an installation-defined data set type 
* write an exit routine for an installation-written syntax checker 


Data Set Types 


An installation can define a data set type for the EDIT command in addition to the data set 
types supplied by IBM. The installation-defined data set types, along with those supplied by 
IBM, must be defined during system generation by using the EDIT macro instruction. (For the 
list of IBM-supplied data set types, see OS/VS2 TSO Command Language Reference. For more 
information on how to specify the EDIT macro instruction during system generation, see 
OS/VS2 System Programming Library: System Generation Reference. The EDIT macro instruction 
builds a table of constants that describes the data set attributes. The EDIT command processor 
supports data sets that have the following attributes: 


Data set organization Sequential or partitioned 

Record format Fixed or variable 

Logical record size Less than or equal to 255 characters 

Blocksize User-specified, must be less than or equal to track length 
Sequence number For variable-length records, first eight characters 


For fixed-length records, last eight characters 
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Syntax Checking 


Each IBM-supplied syntax checker is associated with one or more IBM-supplied data set types. 
If an installation defines its own data set type(s) for the EDIT command, the system 
programmer can write a syntax checker for each new data set type, if desired. Each syntax 
checker and its associated data set type must be defined during system generation by using the 
EDIT macro instruction. (See OS/VS2 System Programming Library: System Generation Reference. 
Thus, when a terminal user enters lines of input to an installation-defined data set type, he can 
request that each line entered in input mode be immediately scanned for syntax errors. 


Before a record is scanned by the appropriate syntax checker, the record is put into the 
terminal user’s data set. If a syntax error is found in the record just entered by the user, EDIT 
displays an error message and switches from input mode to edit mode to enable the user to 
correct the mistake. The formats of the records passed to the syntax checkers are described in 
Figure 10. 


Data Line Number Line Number 







Data 


Fixed- 
Length 
(Numbered) 
8 Bytes 8 Bytes 
—_ Record _ 
Record Length Data Line Number 


Line Number 


Variable- 
Length 
(Numbered) 


ial Bytes as Bytes 
Record Data 


Figure 10. Format of Records Passed to Syntax Checkers 


A standard interface is provided to enable the EDIT modules to invoke any available syntax 
checker. The EDIT modules that invoke syntax checkers, and the IBM-supplied syntax checkers 
are shown with the standard interface in Figure 11. An installation-written syntax checker can 
also use this interface, which consists of the syntax checker parameter list. 
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EDIT Module Standard Interface Syntax Checker 

























Syntax Checker 
Parameter List 


fools puffer 


Data Set Module 
Type Name 


Common Module 
Name Name 





































SCAN IKJEBESC PL1 — PLISCAN 
SCAN — IKJEBESN } 00 || pa eaaeteind oe PL1-F — PLIFSCAN 
CHANGE — IKJEBECG FORTE — IPDSNEXC 
CHANGE — IKJEBECN | 00 [4 OptionWord == || FORTG = — _IPDSNEXC 
INPUT — IKJEBEIM FORTH — IPDSNEXC 
INSERT — IKJEBEIS FORTGI  — IPDSNEXC 
ITE TRANSLATION GOFORT — IPDSNEXC 

— IKJEBEMR BASIC — IKJNC211 
Insert/Replace/Delete IPLI — IKJNC211 

— IKJEBELI user type — user module 
RUN — IKJEBERU 


DELETE — IKJEBEDE 






Figure 11. Interface Between EDIT Program and Syntax Checkers 


The following figures describe the contents of the control blocks pointed to by the syntax 
checker parameter list. 


Disp Field Field 
Dec. Name Size Contents 
C Number of records in buffer (maximum—127); bit zero is set 
to 1 when the syntax checker has scanned all records in the 
buffer. 


pot fot | cham | oa Address of next buffer; set to zero if this is last buffer in chain. 


lta | 


Figure 12. Contents of the Buffer Control Block 








Line or lines of source input data to be syntax checked; can be 
fixed- or variable-length, numbered or unnumbered. 
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Contents 


Meaning 
(Instructions to Syntax Checker) 


(where n=0 or 1). 


First entry — obtain and initialize work area; if a 
buffer chain is supplied, the syntax checker will set 
the relative line number counter to zero. 


Last entry — release the work area and return; syntax 
checking is not performed. 


Normal entry — set relative line number counter to 
zero; perform syntax checking. 


Entry after return code 8 (error - buffer checking 
incomplete) — continue syntax checking. 


Entry after return code 12 (complete statements have 
been checked, but last statement in input buffer is 
incomplete): if there is no more input (chain address 
of last buffer or buffer address is zero), syntax check 
the incomplete statement and return; if there is a 
new buffer chain, that is, more input (chain address 
or buffer address is not zero), resume syntax checking 
at the incomplete statement. 


Reserved. 


Address of work area stored by syntax checker on 
first entry. 


Initial entry — maximum statement size specified at 
SYSGEN (if 0, checker assumes sufficient storage for 
largest legal statement is available); entry after return 
code 4 (error detected, syntax checking complete, 
second -level message present), or 8 (error detected, 
syntax checking incomplete) — address of error 
message area. 


Initial entry — Temporary work area; subsequent 
entries — address of second error message, if any. 


Temporary storage area used for GETMAIN. 





Figure 13. Contents of the Syntax Checker Communication Area 
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Figure 14. Contents of the Option Word 
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Contents 


Meaning 


FORTRAN H level 
FORTRAN E level 
FORTRAN G level 
GOFORT 
FORTRAN G1 


IPLI level 
BASIC level 


Value of left source margin 


Reserved 

FORTRAN G/G1/H Code and Go 
definition to be loaded on initia! 
entry 

FORTRAN G/G1/H Code and Go 
definition not to be loaded on 
initial entry 

FORTRAN E definition to be loaded 
on initial entry 

FORTRAN E definition not to be 
loaded on initial entry 


Entry from INPUT, Insert, linenum, *, 
CHANGE 


Entry from DELETE 

Entry from MERGE or RENUM 
Translation already complete 
Entry from RUN 

Reserved 

Value of right source margin 


Record length of fixed - length records; 
binary zero, if variable-length 
records. 


CHAR 60 

CHAR 48 

Line-numbered data set 

Data set not line-numbered 

Reserved 

Diagnose an incomplete statement 

Delayed scan — return with code of 
12 if last statement in input buffer 
is incomplete; immediate scan — 
possible incomplete statement in 
buffer. 

Fixed-length records 

Variable-length records 

Standard form source input 

Free form source input 


SCAN or SCAN ON specified 
NOSCAN or SCAN OFF specified 


Syntax 
Checker 


FORTRAN 
FORTRAN 
FORTRAN 
FORTRAN 
FORTRAN 


IPLI 
BASIC 


PLIF 


FORTRAN 
FORTRAN 


FORTRAN 


FORTRAN 


FORTRAN 


IPLI or BASIC 


IPL! or BASIC 
IPLI or BASIC 
IPLI or BASIC 
IPLI or BASIC 


IPLI or BASIC 


PLIF 


PLI or IPLI 
PLI or IPLt 
All 
All 
All 
All 
All 





Writing Installation Exits For Syntax Checkers 


For IBM-supplied data set types and associated syntax checkers, each syntax checker 
determines the attributes of the associated data set type by referring to information that EDIT 
initialization sets in the option word, a fullword in the syntax checker parameter list. However, 
for an installation’s own data set type and syntax checker, EDIT initialization does not place 
the attribute information in the option word; the system programmer can write an exit routine 


to fill the option word for the syntax checker according to information entered by a terminal 
user. 


When a terminal user specifies the installation’s data-set-type keyword on the EDIT 
command, he can also specify a subfield. The subfield can contain any alphameric data defined 
as valid, not exceeding 256 characters and not containing any blanks, tabulation characters, or 
commas. This information is passed to the exit routine to be interpreted and encoded into 
bytes O and 1 of the option word. 


The exit routine name must be supplied during system generation as the USREXT value for 
the applicable data set type(s) on the EDIT macro instruction. The routine receives control 
from EDIT command processor via a LINK macro instruction, and it must follow standard 
linkage conventions. 


Upon entry, register 1 points to a three-word parameter list. The contents of the parameter 
list are: 


Word 1 
Address of the subfield parameter descriptor element (PDE) with the following format: 


Bytes Meaning 
4 Address of the character string (zero, if the character string 1s omitted) 
Zz Length of the character string 


| Flag bits: High-order bit set to 0, the parameter is not present. High-order bit set to 1, 
the parameter is present. The other bits are unused. 
l Reserved 
For more information on this PDE, see OS/VS2 TSO Guide to Writing a Terminal Monitor 
Program or Command Processor, for a description of the IKJIDENT PDE under ''Format of the 
PDEs Returned By Parse." 


Word 2 
Address of bytes O and 1 of the syntax checker option word. The installation-written syntax 
checker can assign its own meanings for the bit settings. 


Word 3 


Address of the command processor parameter list (CPPL) passed to the EDIT command 
processor from TMP. The format of the CPPL is: 


Bytes Field name Meaning 

4 CPPLCBUF The address of the command buffer. 

4 CPPLUPT The address of the user profile table (UPT). 

4 CPPLPSCB The address of the protected step control block (PSCB). 
4 CPPLECT The address of the environment contro! table (ECT). 


The exit routine uses this information to access the ECT and UPT to invoke parse or a TMP 
service routine. 


The exit routine is expected to update bytes O and 1 of the option word and to issue a 
return code: O if successful, 4 if unsuccessful. 
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Adding Subcommands To The EDIT Command 


When a terminal user enters an EDIT subcommand, the edit controller (load module 
IKJEBEMA) invokes the appropriate subcommand processor. IKJEBMA9, a CSECT within load 
module IKJEBEMA, is reserved as a table of installation-written EDIT subcommand names. 
Thus, if an installation requires an editing function not provided by the IBM-supplied EDIT 
subcommands, the system programmer can write one or more subcommand processors and add 
their names to this table by using the IKJEBEST macro instruction. The operands of the 
IKJEBEST macro instruction indicate the name of the subcommand, the abbreviation for the 
subcommand name, the name of the module that processes the subcommand, and the 
CSECT=USER operand. For example: 


TKRJBBEST ( SWITCH, SW, XXXSWTCH ) ,CSECT=USER 


To specify multiple subcommand processors via IKJEBEST, the format is: 
LKJEBEST (subcmd,,abbr,,mod-name,)[,...],CSECT=USER 


Note: The names associated with an installation-written subcommand must not be the same as 
the names associated with any IBM-supplied subcommands. 


When the IKJEBEST macro instruction is assembled, the CSECT=USER operand causes the 
resulting object module to be named IKJEBMA9. The system programmer must linkage-edit the 
IKJEBMA9 module with the IKJEBEMA load module, performing a CSECT-replacement operation 
for IKJEBMA9 object module. At that point, the installation-written EDIT subcommands are 
available. 


Executing Authorized Programs Under TSO 


TSO users cannot execute authorized programs interactively. This restriction includes the OS/VS 
utility programs IEHDASDR IEBCOPY, IEHMOVE, IEHATLAS, IEHINITT and IEHPROGM. TSO 
users can, however, execute these utilities by using the SUBMIT command. 


If an installation desires to override this restriction, it can do the following: 


1. Re-linkedit the terminal monitor program (TMP; IKJEFTO1,) assigning it a different 
name and authorizing it. Authorization is assigned by means of a new parameter in the 
linkage edit step or a new linkage editor control statement. 


2. Write a logon procedure that specifies the name of the authorized TMP as the program 
name to be executed. 


3. Use the ACCOUNT logon procedure created in step 2. 


An installation that decides to authorize a TMP must be aware of possible system integrity 
exposures that might exist when using TSO commands, which were not designed to execute 
authorized, and when using installation-written command processors. If any LINK, LOAD, XCTL 
or ATTACH is issued and the module is found in an unathorized library, the result will be that 
the issuing task is abended with system completion code 306. (See "Defining Authorized 
Libraries" in OS/VS2 System Programming Library: Supervisor. ) 
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Part 2: Reference — TSO Commands 


You can communicate service requests to the control program using a set of macro instructions 
and commands provided by IBM. Whereas most of the macro instructions and commands have 
no restrictions on use by applications programmers and console operators, some of them 
should be restricted in use to systems programmers and installation-approved personnel. 


Note: For more information on restricted macro instructions, refer to OS/VS2 SPL: Supervisor. 


This section describes the TSO commands that should be installation controlled. The 
ACCOUNT and OPERATOR commands should be totally restricted in use. These commands are 
completely described in this book. 


Coding the Commands 


The table appearing near the beginning of each command or subcommand indicates how each 
is to be coded. The table does not attempt to explain the meanings of the parameters; the 
parameters are explained in the text following the table. See the Figure 15 for a sample 


subcommand. 
CHANGE 
C 
b One or more blanks must follow CHANGE or C. 
( 
A+} userid userid: 1-7 alphameric characters, beginning with an alphabetic or 
ss national character. 
b password password: \-8 alphameric characters. 
b * 
6 acct nmbr acct nmbr: up to 40 characters, not containing a blank, quotation 
6 * mark, apostrophe, comma, semicolon, or line control. 
Note: This parameter may only be specified if the preceding 
parameter (password or *) is also specified. 
6 proc proc: \-8 alphameric characters, beginning with an alphabetic 
b * character. 


Note: this parameter may only be specified if the preceding 
parameter (acct nmbr or * is also specified. 


) 


6 UNIT (name) name: 1-8 alphameric characters. 
6) 6b MAXSIZE (rgn_ size) rgn size: decimal digits less than 65,535. 
Bb NOLIM 


Figure 15. Sample Subcommand 


« The first column(A), contains those parameters that are required for that TSO command 
or subcommand. If a single line appears in that column (Al), the parameter on that line is 
required and must be coded. If two or more lines appear (ogether, (A2), the parameter 
appearing on one and only one of the lines must be coded. 


e The second column(B ) contains those parameters that are optional for that TSO 
command or subcommanad. If a single line appears in that column,(B1) , the parameter on 
that line is optional. If two or more lines appear together,(B2) , the parameter appearing 
on one and only one of the lines may be coded if desired. 
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e The third column,(C), provides additional information for coding the TSO command or 
subcommand. When substitution of a variable is required, the following classifications 
should be understood: 


symbol: any symbol valid in the assembler language. That is, an alphabetic character followed 
by 0-7 alphameric characters, with no special characters and no blanks. 


decimal digit: any decimal digit up to the value indicated in the parameter description. If both 
symbol and decimal digit are indicated, an absolute expression is also allowed. 


default: a value that is used in default of a specified value, and that the system assumes if the 
parameter is not coded. 


*: represents a null field when creating a new data set. 


Use the parameters to specify the services and options to be performed, and write them 
according to the following general rules: 


e If the selected parameter is written in all capital letters (for example, ACCT or OPER), 
code the parameter exactly as shown. 


e If the selected parameter is written in italics (for example, value or pdsname), substitute 
the indicated value, or pds name. 


e Read the table from top to bottom, and code the parameters in the order shown. Code 
commas and parentheses exactly as shown. 


e If a parameter is selected, read column 3 before proceeding to the next parameter. 
Column 3 will often contain notes pertaining to restrictions on coding the parameter. 
Continuation Lines 
You may continue a command or subcommand on one or more lines by following this rule: 


Continuation of a command may be done by using a hyphen (minus sign) or a plus sign. 
Placing either one of these special characters as the last character on the line will allow you to 
continue to the next line . One caution should be observed, the plus sign will cause the 
deletion of any leading delimiters on the continued line. 
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ACCOUNT Command 


Use the ACCOUNT command and subcommands to create and update the entries in the user 
attribute data set (UADS) and, simultaneously, the broadcast data set. (SYS1.BRODCAST) 
This command can be executed as either a time-sharing or a batch job. (You can use this 
command only if your installation has given you the authority to do so.) Basically, the UADS is 
a list of terminal users who are authorized to use TSO. The UADS contains information about 
each of the users. The information in the UADS is used to regulate access to the system. The 
broadcast data set can contain notices and mail for all USERIDs which are defined to it. 


The ACCOUNT command is written as follows: 


ACCOUNT 


The SYS1.UADS data set must be allocated as SHR prior to using the ACCOUNT command. You 
cannot accomplish any work with the ACCOUNT command until you use a subcommand to 
define the operation that you want to perform. The subcommands and the operations that they 
define are: 

ADD Add new entries to the UADS; add new data to existing entries. 


CHANGE Change data in specified fields of UADS entries. 
DELETE Delete entries or parts of entries from the UADS. 


END Terminate the ACCOUNT command. 

HELP Obtain help from the system. (Not available for batch jobs.) 

LIST Display the contents of an entry in the UADS. 

LISTIDS Display the user identifications for all entries. 

SYNC Build a new SYSI.BRODCAST data set and synchronize it with the UADS. 


In MVS, TSO users can be authorized (by means of the MOUNT parameter of the ACCOUNT 
subcommands ADD and CHANGE) to allow volumes to be mounted. The volume request can 
be either explicit (for example, which the ALLOCATE command is issued) or implicit (for 
example, with commands that cause temporary space to be allocated). There is no message 
sent to the user indicating that operator action has been requested at the time the volume is 
mounted. The user will sit in a "locked out" condition at the terminal until the operator has 
responded to the request. Users authorized to allow volume mounting should be aware of this 
situation. It is advisable to send the operator a message prior to issuing the command 
requesting a particular volume. 
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ADD Subcommand of ACCOUNT 


Use the ADD subcommand to create new userids for prospective users of TSO. As you create a 
new userid, a corresponding entry is created in the user attribute data set (UADS) for that user. 
For each new userid that you create, the system builds a ''typical'’ user profile in the user 
profile table (UPT) for that user. 


You can also use ADD to add additional data to an existing entry in the UADS. Do not use 
ADD to change any existing data in a UADS entry; use the CHANGE subcommand instead. 


When adding a new entry to the UADS, you can also select the following options for the 
new user: 


« The region size that he can request at LOGON. 

e The authority to use the ACCOUNT command. 

¢ The authority to use the OPERATOR command. 

e The authority to use the SUBMIT, STATUS, CANCEL, and OUTPUT commands. 
e The authority to specify performance groups at LOGON. 

e The authority to specify dynamic allocation requests for volume mounting. 

e The authority to specify remote work stations for SYSOUT data sets. 

¢ The installation defined data to be added to the entry. 


The ADD subcommand of ACCOUNT is written as follows: 
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ADD 


6 DATA (password 6 

acct nmbr 6 proc) 
6 DATA (acct nmbr 6 proc) 
6 DATA (proc) 


6 SIZE (rgn size) 
6 UNIT (name) 


b MAXSIZE (ren size) 
b NOLIM 


6 ACCT 
6 NOACCT 


6b OPER 
6 NOOPER 


6 JCL 
6 NOJCL 


6 USERDATA (data) 


6 PERFORM (perf groups) 
6b NOPERFORM 


6 MOUNT 
6 NOMOUNT 


6 DEST (userid) 
6 NODEST 


A 
ie) One or more blanks must follow ADD or A. 
( 
userid userid: 1-7 alphameric characters, beginning with an alphabetic or 
* national character. 
6 password password: |-8 alphameric characters. 
® * 
6 acct nmbr acct nmbr: Up to 40 characters, not containing a blank, tab, 
6 * quotation mark, apostrophe, comma, semicolon, or line control 
character. 
Note: This parameter may only be specified if the preceding 
parameter (password or *) is also specified. 
b proc proc: \-8 alphameric characters, beginning with an alphabetic 
6 * character. 


Note: This parameter may only be specified if the preceding 
parameter (acct nmbr or *) ts also specified. 


password: List of passwords (1-8 alphameric characters), separated 
by commas or blanks. 

acct nmbr: List of account numbers (up to 40 characters, not 
containing a blank, tab, quotation mark, apostrophe, comma, 
semicolon, or line control character), separated by commas or 
blanks. 


proc: List of procedure names (1-8 alphameric characters, beginning 
with an alphabetic character), separated by commas or blanks. 


rgn size: decimal digits less than 65,535. 
name: \-8 alphameric characters. 


rgn size: decimal digits less than 65,535. 
Default: NOLIM 


Default: NOACCT 
Default: NOOPER 
Default: NOJCL 


data: 4 hexadecimal digits. 


perf groups: \ist of decimal digits 1-255, separated by commas or 
blanks. 


Default: NOPERFORM 
Default: NOMOUNT 


userid: \-7 alphameric characters, beginning with an alphabetic or 
national character. 
Default: NODEST 


The parameters are explained below: 


The first positional parameter specifies the point within the UADS structure where data is to be 
added. If all four items are specified, a new USERID will be created. 


If less than four items are specified, information will be added to an existing USERID. The sum 
of the items in the positional list and the DATA list must equal four. 


An asterisk (*) indicates a null field when you are creating a new entry. 
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specifies the beginning of a series of positional parameters. 


userid 

* 
specifies a user identification that identifies the UADS entry and the entry in the 
SYS1.BRODCAST data set for the user (userid) or specifies that information for all user 
identifications in the UADS is to be added (*). The entry that this field identifies may be an 
existing entry to which new data is to be added or a new entry that is to be added to the 
UADS. 


6 password 

6 * 
specifies a word that a user must enter before he can use the system (password) or specifies 
all passwords for the indicated user identification (*). The password helps indicate the 
structure in the UADS to which data is being added or, when you are adding an entire new 
entry, the password is part of the data being added. 


® acct nmbr 

ca) * 
specifies an account number used for administrative purposes (acct nmbr) or specifies all 
account numbers for the indicated password for the indicated user identification(*). The 
account number helps indicate the structure in the UADS to which data is being added or, 
when you are adding an entire new entry, the account number is part of the data being 
added. 


® proc 

H * 
specifies the name of a procedure that is invoked when the user enters the LOGON 
command (proc) or specifies all procedure names for the indicated account number for the 
indicated password for the indicated user identification (*). You should not specify this field 
for the first positional parameter unless you are adding an entire new entry to the UADS. 


specifies the end of a series of positional parameters. 


6 DATA (password 6 acct nmbr 6 proc) 
fi DATA (acct nmbr © proc) 
6 DATA (proc) 
specifies the data that is to be added to the existing entry: 


password specifies a password or a list of passwords to be added to the existing entry at 
the location indicated by the positional parameter. When you specify a list of passwords, 
the list must be enclosed within a separate set of parentheses embedded within the set of 
parentheses required for the DATA keyword. 


acct nmbr_ specifies an account number of a list of account numbers to be added to the 
existing entry. When you specify a list of account numbers, the list must be enclosed 
within a separate set of parentheses embedded within the set of parentheses required for 
the DATA keyword. No more than 255 identical account numbers may exist under one 
password in a user entry. 
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proc specifies a procedure name or a list of procedure names to be added to the existing 
entry. When you specify a list of procedure names, in addition to one or more other 
fields, the list must be enclosed within separate set of parentheses embedded within the 
set of parentheses required for the DATA keyword. You should specify the region size 
requirements and device units for each procedure by using the SIZE and UNIT keyword. 
No more than 255 identical procedure names may exist under one account number in a 
user entry. 


6 SIZE (rgn_ size) 
specifies the minimum region size, in 1024-byte units, that the user will have assigned to 
him if he does not specify a size himself. You can specify a SIZE attribute for each unique 
combination of password, account number, and procedure name in the entry. If you specify 
SIZE(O), the default value is the minimum size available. 


6 UNIT (name) 
specifies the name of a group of devices that the procedure will use. (Data sets allocated via 
the catalog are an exception. See the ALLOCATE command in the OS/VS2 TSO Command 
Language Reference. You can specify a UNIT attribute for each unique combination of 
password, account number, and procedure in the entry. 


fH MAXSIZE (rgn_ size) 

i NOLIM 
specifies the maximum region size, in 1024-byte units, that the user may request at LOGON 
(MAXSIZE) or that the user is not restricted to a maximum region size (NOLIM). If you 
specify MAXSIZE(0), the default of NOLIM is assumed. Use this parameter only when you 
add a complete entry to the UADS. 


6 ACCT 

® NOACCT 
specifies that the user can (ACCT) or cannot (NOACCT) use the ACCOUNT command, 
thereby controlling access to the time sharing system. Use this parameter only when you 
add a complete entry to the UADS. 


6 OPER 

i NOOPER 
specifies that the user can (OPER) or cannot (NOOPER) use the OPERATOR command. Use 
this parameter only when you add a complete entry to the UADS. 


6 JCL 

6 NOJCL 
specifies that the user can (JCL) or cannot (NOJCL) use the SUBMIT, STATUS, CANCEL. and 
OUTPUT commands. Use this parameter only when you add a complete entry to the UADS. 


fH USERDATA (data) 
specifies what the installation-defined data is to be added to in the user entry in the UADS. 
The two-byte field in the UADS is the EBCDIC representation of the four hexadecimal 
characters specified as data. The meaning of the field is defined by the user. Use this 
parameter only when you add a complete entry to the UADS. 


fH PERFORM (perf groups) 

6 NOPERFORM 
specifies that the TSO user is (PERFORM) or is not (NOPERFORM) authorized to request 
performance groups at logon. A default performance group will result from the TSO user’s 
logon procedure. Use this parameter only when you add a complete entry to the UADS. 
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6 MOUNT 

i NOMOUNT 
specifies that dynamic allocation requests for this TSO userid are (MOUNT) or are not 
(NOMOUNT) authorized to cause volume mounting as necessary. Use this parameter only 
when you add a complete entry to the UADS. 


6 DEST (userid) 

 NODEST 
specifies whether there is (DEST) or is not (NODEST) a default destination to which SYSOUT 
data sets defined by this user will be routed. This default can be overridden by ALLOCATE. 
FREE, and other commands. Use this parameter only when you add a complete entry to the 
UADS. 


Example 1 


Operation: Add a new entry to the UADS. 


add (warner] xaybzc 32058 mylog) noacct nooper jcl - 
maxsize( 150) size(80) unit(sysda) userdata(1fa8) perform (15624) 
dest(deptout) mount 


Example 2 


Operation: Add a new password, account number, and procedure name to an existing entry in 
the UADS. Also include the region size requirements for the procedure. 


add (warner1) data(mz3tiil 7116166 amabala) s1ize(90) 


Example 3 


Operation: Continuing example 2, add a new account number, 288104 to an existing entry in 
the UADS. 


add (warner? mz3ti1) data(288104 mylog) size(114) unit(sysda) 


Example 4 


Operation: Add a new procedure name, and the region size requirements for it, to all entries 
in the UADS. 


add (* * *) data(mylog) size(73) 


Example 5 


Operation: Add a new account number and new procedure name to all structures under an 
existing entry in the UADS. 


add (warner!) *) data(5707471 logproc) size( 100) 
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CHANGE Subcommand of ACCOUNT 


C 


Use the CHANGE subcommand to change existing fields of data within entries in the UADS. 


The CHANGE subcommand of ACCOUNT is written as follows: 





CHANGE 
C 
b One or more blanks must follow CHANGE or C. 
J ( 
userid userid: 1-7 alphameric characters, beginning with an alphabetic or 
* national character. 
6 password password: \-8 alphameric characters. 
b * 
6 acct nmbr acct nmbr: up to 40 characters, not containing a blank, quotation 
6 * mark, apostrophe, comma, semicolon, or line control. 
Note: This parameter may only be specified if the preceding 
parameter (password or *) is also specified. 
6 proc proc: 1-8 alphameric characters, beginning with an alphabetic 
b * character. 
Note: This parameter may only be specified if the preceding 
parameter (acct nmbr or *) is also specified. 
) 


6 DATA (userid) 

6 DATA (password) 
6 DATA (acct nmbr) 
6 DATA (proc) 


6 SIZE (rgn size) 
6 UNIT (name) 


6 MAXSIZE (rgn_ size) 
6 NOLIM 


b ACCT 
6 NOACCT 


6 OPER 
6 NOOPER 


6 JCL 
6 NOJCL 


6 USERDATA (data) 


6b PERFORM (perf groups) 


6 NOPERFORM 


6b MOUNT 
6 NOMOUNT 


6b DEST (userid) 
b NODEST 


userid: 1-7 alphameric characters, beginning with an alphabetic or 
national character. 

password: 1-8 alphameric characters. 

acct nmbr: up to 40 characters, not containing a blank, tab, 
quotation mark, apostrophe, comma, semicolon, or line control 
character. 

proc: \-8 alphameric characters, beginning with an alphabetic 
character. 


rgn size: decimal digits less than 65,535 
name: 1-8 alphameric characters. 


rgn size: decimal digits less than 65,535. 


data: 4 hexadecimal digits. 


perf groups: \ists of decimal digits 1-255, separated by commas or 
blanks. 


userid: \-7 alphameric characters, beginning with an alphabetic or 
national character. 


The parameters are explained below: 


( 
( specifies the beginning of a series of positional parameters. 
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userid 

* 
specifies a user identification that identifies the UADS entry to be changed (userid) or 
specifies that all user identifications in the UADS are to be changed (*). 


6 password 

se) * 
specifies a word that a user must enter before he can use the system (password) or specifies 
all passwords for the indicated user identification (*). The password helps locate the data 
begin changed and, when you are changing a password, identifies the password being 
changed. 


fH acct nmbr 

6 * 
specifies an account number used for administrative purposes (acct nmbr) or specifies all 
account numbers for the indicated password for the indicated user identification (*). The 
account number helps locate the data being changed and, when you are changing an 
account number, identifies the account number being changed. 


6 proc 

se) of 
specifies the name of a procedure that is invoked when the user enters the LOGON 
command (proc) or specifies all procedure names for the indicated account number for the 
indicated password for the indicated user identification(*). The procedure name, when 
specified, is the data being changed. 


— 


specifies the end of a series of positional parameters. 


) DATA (userid) 

DATA (password) 

DATA (acct nmbr) 

DATA (proc) 

specifies the data that is to be changed from the existing entry: 


ok mom Oo 


userid specifies a user identification to replace the existing user identity. 
password specifies a password to replace the existing password. 

acct nmbr_ specifies an account number to replace the existing procedure name. 
proc specifies a procedure name to replace the existing procedure name. 


6 SIZE (rgn_ size) 
specifies the minimum region size, in 1024-byte units that the user will have assigned to him 
if he does not specify a size himself. You can specify a SIZE attribute for each unique 
combination of password, account number, and procedure name in the entry. If you specify 
SIZE(0), the default value is the minimum size available. 


6 UNIT (name) 
specifies the name of a group of devices that the procedure will use. (Data sets allocated via 
the catalog are an exception. See the ALLOCATE command in the OS/VS2 TSO Command 
Language Reference. 


fH MAXSIZE (rgn_ size) 

6 NOLIM 
specifies the maximum region size, in 1024-byte units, that the user may request at LOGON 
(MAXSIZE) or that the user is not restricted to a maximum region size (NOLIM). If you 
specify MAXSIZE(0), the default of NOLIM is assumed. 
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6 ACCT 

 NOACCT 
specifies that the user can (ACCT) or cannot (NOACCT) use the ACCOUNT command, 
thereby controlling access to the UADS. 


6 OPER 
® NOOPER 
specifies that the user can (OPER) or cannot (NOOPER) use the OPERATOR command. 


6 JCL 
6 NOJCL 


specifies that the user can (JCL) or cannot (NOJCL) use the SUBMIT, STATUS, CANCEL, and 
OUTPUT commands. 


6 USERDATA (data) 
specifies what the installation-defined data is to be changed to in the user entry in the 


UADS. The two-byte field in the UADS is the EBCDIC representation of the four hexadecimal 
characters specified as data. The meaning of the field is defined by the user. 


H PERFORM (perf groups) 

i NOPERFORM 
specifies that the TSO user is (PERFORM) or is not (NOPERFORM) authorized to request 
performance groups at logon. A default performance group will result from the TSO user’s 
logon procedure. 


6 MOUNT 

® NOMOUNT 
specifies that dynamic allocation requests for this TSO userid are (MOUNT) or are not 
(NOMOUNT) authorized to cause volume mounting as necessary. 


6 DEST (userid) 

® NODEST 
specifies whether there is (DEST) or is not (NODEST) a default destination to which SYSOUT 
data sets defined by this user will be routed. This default can be overridden by ALLOCATE, 
FREE, and other commands. This parameter is meaningful only when a TSO user is being 
created or modified. 


Example 1 


Operation: Change an account number for an entry in the UADS and authorize the user to 
issue the ACCOUNT and OPERATOR commands. 


change (slc0O5 aox3p se29705) data(2e26705) acct oper 


Example 2 


Operation: Authorize all users to issue the SUBMIT command. 


change (*) jcl 


The asterisk in the first positional parameter position specifies that all user identities are 
considered valid for the operation of this subcommand. 


Example 3 


Operation: Change the user identification for an entry in the UADS. 


change (warner) data(renwar } 
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Example 4 


Operation: Change the name of a procedure for an entry that consists of a user identification, 
a procedure name, and attributes (no password or account number). 


change (jal95 * * oldproc) data(newproc ) 
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DELETE Subcommand of ACCOUNT 


Use the DELETE subcommand to delete data from the user attribute data set (UADS). Each 
terminal user has an entry in the UADS. Each entry contains several items of data. The data 
that you want to delete may be a part of an existing entry. 


The DELETE subcommand of ACCOUNT is written as follows: 


DELETE 


D 
b 


( 


userid 


* 


b password 
x 


6 
6 acct nmbr 
6 


* 


6b DATA (password) 
6 DATA (acct nmbr) 
6 DATA (proc) 


One or more blanks must follow DELETE or D. 


userid: 1-7 alphameric characters, beginning with an alphabetic or 
national character. 


password: |-8 alphameric characters. 


acct nmbr: up to 40 characters, not containing a blank, tab, 
quotation mark, apostrophe, comma, semicolon, or line control 
character. 

Note: This parameter may only be specified if the preceding 
parameter (password or *) is also specified. 


password: \ist of passwords (1-8 alphameric characters), separated 
by blanks or commas. 

acct nmbr: list of account numbers ( up to 40 characters, not 
containing a blank, tab, quotation mark, apostrophe, comma, 
semicolon, or line control character), separated by blanks or 
commas. 

proc: list of procedure names (1-8 alphameric characters, beginning 
with an alphabetic character), separated by commas or blanks. 


The parameters are explained below: 


( 


specifies the beginning of a series of positional parameters. 


userid 


* 


specifies a user identification that identifies the UADS entry to be deleted (userid) or 
specifies that all user identifications in the UADS are to be deleted(*). 


4 password 
58) * 
specifies a word that a user must enter before he can use the system (password) or specifies 
all passwords for the indicated user identification(*). The password helps indicate the 
particular existing structure from which data is being deleted or, when you are deleting a 
password, the password is the data being deleted. 


6 


acct nmbr 


5 * 
specifies an account number used for administrative purposes (acct nmbr) or specifies all 
account numbers for the indicated password for the indicated user identification (*). The 
account number helps indicate the structure from which data is being deleted or, when you 
are deleting an account number, the password is the data being deleted. 
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54 


specifies the end of a series of positional parameters. } 


6 DATA (password) 
H DATA facct nmbr) 
DATA (proc) 
specifies the data that is to be deleted from an existing entry: 


password specifies a password or list of password to be deleted from the existing entry at 
the location indicated by the first positional parameter. 


acct nmbr_ specifies an account number or list of account numbers to be deleted from the 
existing entry. 


proc specifies a procedure name or list of procedure names to be deleted from the existing 
entry. 


Deleting an Entire Entry: To delete an entire entry from the UADS, you only need to know 
the user identification for the entry. You must specify the user identification as the first and 
only field of the first positional parameter. 


Deleting Data from an Existing Entry: Yo use the DELETE subcommand to delete data from 
an existing entry, you must identify: 


a. The location within the entry. 


b. The data that you want to delete. 


Example 1 


Operation: Delete an entire entry from the UADS. 
delete (early08) o 


Example 2 


Operation: Delete a procedure name from an entry in the UADS having the following index 
structure. 


SCHRDNY 


TG2A7 EGCLON 


842244124 3707656 ' 


PROGA PROCS proce | | pRoeB | 
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Example 3 


Operation: Delete an account number from an entry in the UADS having the following index 
structure. 





DELETE Subcommand of ACCOUNT 55 


END Subcommand of ACCOUNT 


Use the END subcommand to terminate operation of the ACCOUNT command. After entering 
the END subcommand, you may enter new commands. 


The END subcommand of ACCOUNT is written as follows: 





END 
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Cc 


HELP Subcommand of ACCOUNT 


Use the HELP subcommand to find out how to use the ACCOUNT subcommands. When you 
enter the HELP subcommand, the system responds by printing out explanatory information at 
your terminal. You may request: 


« A list of available subcommands. 
« An explanation of the function, syntax, and parameters of a specific subcommand. 


The HELP subcommand actually causes the system to execute a function of the HELP 
command; therefore, you may wish to consult the discussion of the HELP command in OS/VS2 
TSO Command Language Reference. 


The HELP subcommand of ACCOUNT is written as follows: 


HELP 
H 
6 subcmd subcmd: symbol (name representing subcommand). 
Default: list of ACCOUNT subcommands. 
6 ALL parms: \ist of symbols (names representing parameters), separated 
6 FUNCTION by commas or blanks. 
6b SYNTAX Default: ALL 
6b OPERANDS Note: This parameter may only be specified if the preceding 
6H OPERANDS (parms) parameter is also specified. 


The parameters are explained below: 


6 subcmd 
specifies the subcommand that you want to have clarified. 


6 ALL 
BH FUNCTION 
6 SYNTAX 
B OPERANDS 
H OPERANDS (parms) 
specifies the explanatory information requested: 


ALL specifies that you want a description of the function, the syntax, and the parameters 
of the subcommand that you specified. 


FUNCTION specifies that you want a description of the referenced subcommand’s function. 


SYNTAX specifies that you want a definition of the proper syntax for the referenced 
subcommand. 


OPERANDS specifies that you want an explanation of the parameters applicable to the 
referenced subcommand. 


parms specifies the particular keywords that you want to have explained. If you do not 
specify any keywords, all of the applicable keywords will be included. 


Example 1 


Operation: Have a list of available subcommands displayed at your terminal. 
help 
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Example 2 


Operation: Obtain all available information about a particular subcommand. 
h add 


Example 3 


Operation: Wave a list of the parameters for a particular subcommand displayed at your 
terminal. 


h change operands 


58 OS/VS2 System Programming Library: TSO (VS2 Release 3) 


LIST Subcommand of ACCOUNT 


C 


Use the LIST subcommand to display entries in the user attribute data set (UADS) or to display 
fields of data from within particular entries. 


The LIST subcommand of ACCOUNT is written as follows: 


LIST 
L 
e 6 One or more blanks must follow LIST or L. 
( 
' userid userid: 1-7 alphameric characters, beginning with an alphabetic or 
# national character. 
6 password password: |-8 alphameric characters. 
b * 
6 acct nmbr acct nmbr: up to 40 characters, not containing a blank, tab, 
b * quotation mark, apostrophe, comma, semicolon, or line control 
character. 
Note: This parameter may only be specified if the preceding 
parameter (password or *) is also specified. 
6 proc proc: 1\-8 alphameric characters, beginning with an alphabetic 
b * character. 
Note: This parameter may only be specified if the preceding 
parameter (acct nmbr or *) is also specified. 
) 
Cc The parameters are explained below: 
( 


specifies the beginning of a series of positional parameters. 


userid 

* 
specifies a user identification that identifies the UADS entry to be listed (userid) or specifies 
that all user identifications in the UADS (*) are to be listed. 


6 password 

6 * 
specifies a word that a user must enter before he can use the system (password) or specifies 
all passwords for the indicated user identification (*). The password helps indicate the 
structure to be displayed. 


6 acct nmbr 
H * 
specifies an account number used for administrative purposes (acct nmbr) or specifies all 
. account numbers for the indicated password for the indicated user identification (*). The 
account number helps indicate the structure to be displayed. 


® proc 

H * 
specifies the name of a procedure that is invoked when the user enters the LOGON 
command (proc) or specifies all procedure names for the indicated account number for the 
indicated password for the indicated user identification (*). The procedure name helps 

C indicate the particular structure to be displayed. 
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specifies the end of a series of positional parameters. 


Example 1 


Operation: List the contents of the UADS. 
list (*) 


Example 2 


Operation: List all of a particular entry in the UADS. 


list (wrrid) 
Example 3 


Operation: List all of the account numbers under a specific password for a particular entry. 
Last: (wrrid £oolt *) 


Example 4 


Operation: List all references to a specific procedure for all entries. 
Lo # <* pr OcO') |) 
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LISTIDS Subcommand of ACCOUNT 


Use the LISTIDS subcommand to have a list of the user identifications in the User Attribute 
Data Set (UADS) displayed at your terminal. 


The LISTIDS subcommand of ACCOUNT is written as follows: 


LISTIDS 
LISTI 


Example 1 


Operation: List all user identifications in the UADS. 
listids 
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SYNC Subcommand of ACCOUNT 


Use the SYNC subcommand to build a new broadcast data set and synchronize it with the 
UADS by entering the userids from the UADS into the broadcast data set. This causes the loss 
of all messages (MAIL) from the broadcast data set. The SYNC subcommand is useful when the 
two data sets have gotten out of synchronization either because of I/O errors in 
SYS1.BRODCAST or because the installation is using a different UADS. 


The SYNC subcommand of ACCOUNT is written as follows: 


SYNC 
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OPERATOR Command 


C 


Use the OPERATOR command (along with its subcommands) to regulate and maintain TSO 


from a terminal. 


The OPERATOR command is fully supported only for terminals that have the 
transmit-interruption capability; that is, this command is supported only for those terminals for 
which the BREAK parameter of the TERMINAL command is valid. Enter TERMINAL command 
with BREAK keyword before issuing the OPERATOR command on an IBM 2260 or an IBM 


3270. 


This command may be used only by personnel who have been given the authority to do so 
by the installation management. The authority to use OPERATOR is normally given to 
, personnel responsible for system operation, and is recorded in the User Attribute Data Set. 


The OPERATOR command is written as follows: 


OPERATOR 


OPER 


The OPERATOR command, through the use of its subcommands, allows the terminal user to 
control TSO as follows: 


CANCEL 
DISPLAY 


END 
C HELP 
MONITOR 


SEND 
STOPMN 


Cancel a terminal session. 

Display the number of TSO users, the number of batch jobs, the TSO job messages that 
are awaiting a reply from the system operator, and the time of day and the date. 
Terminate the OPERATOR command (thereby removing the user's terminal from 
OPERATOR mode). 

Get a list of the subcommands of the OPERATOR command, along with the function, 
syntax, and parameters of the subcommands. 

Monitor both terminal and background job activities within the system. Informational 
messages will be displayed. 

Send a message to other terminal users or operators. 

Terminate the monitoring operations of the MONITOR subcommand; the display of 
information messages at the user's terminal will be stopped. 
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CANCEL Subcommand of OPERATOR J 


Use the CANCEL subcommand to terminate the current activities of a terminal user. When you 
use the CANCEL command to terminate a terminal session, accounting information will be 
presented to the user. 


The CANCEL subcommand of OPERATOR is written as follows: 


CANCEL 
C ; 
6 One or more blanks must follow CANCEL or C. 
U=userid userid: 1-7 alphameric characters, beginning with an alphabetic or ‘ 
national character. 
DUMP 


The parameters are explained below: 


U =userid 
specifies the user identification for a user whose terminal session is to be terminated. 


,DUMP 


specifies that an abnormal-end-of-job storage dump is to be taken. The dumps will be 
printed on the system output device. 


Example 1 


Operation: Terminate a user’s terminal session with a dump. J 


C u=silcid,dump 
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DISPLAY Subcommand of OPERATOR 


Use the DISPLAY subcommand to obtain a listing of: 


e The number of TSO users. 

e The number of batch jobs awaiting execution. 

« The messages from time sharing jobs that are awaiting replies from an operator. 
e The time of day and the date. 


The DISPLAY subcommand of OPERATOR is written as follows: 


DISPLAY 

D 

b One or more blanks must follow DISPLAY or D. 

T 

TS 

R 

J 

JOBS 
ns Note: This parameter may not be used with T above. 
sLIST 


The parameters are explained below: 


T 
TS 
R 
J 
JOBS 
specifies the information to be displayed at the terminal: 


T specifies that you want the time of day and the date. 
TS specifies that you want the number of TSO users currently logged on the system. 


R specifies that you want a listing of the ids of messages that are awaiting a response from 
an operator. 


J and JOBS specify that you want the number of batch jobs awaiting execution. 


ks 
sLIST 
specifies that you want the following additional information displayed: 


For TS, a list of TSO userids currently logged on the system. 
For R, a list of the beginnings of the messages corresponding to the ids. 


For J and JOBS, a list of the jobnames and V=R region boundaries. 


Example 1 


Operation: Display the number of, and a list of, the TSO users currently logged on. 
d ts, list 
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Example 2 


Operation: Display the time of day and the date. 
d is 
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END Subcommand of OPERATOR 


Use the END subcommand to terminate operation of the OPERATOR command. After entering 
the END subcommand, you may enter new commands. 


The END subcommand of OPERATOR is written as follows: 


END 
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HELP Subcommand of OPERATOR 


Use the HELP subcommand to find out how to use the OPERATOR subcommands. When you 
enter the HELP subcommand, the system responds by printing out explanatory information at 
your terminal. You may request: 


« A list of available subcommands. 
« An explanation of the function, syntax, and parameters of a specific subcommand. 


The HELP subcommand actually causes the system to execute a function of the HELP 
command; therefore, you may consult the discussion of the HELP command in OS/VS2 TSO ; 
Command Language, if you desire more detailed information. 


The HELP subcommand of OPERATOR is written as follows: 


HELP 
H 
6 subcmd subcmd: symbol (name representing subcommand). 
Default: list of OPERATOR subcommands. 
6b ALL parms: \ist of symbols (name representing parameters), separated by 
6 FUNCTION commas or blanks. 
6 SYNTAX Default: ALL 
6 OPERANDS 


6 OPERANDS (parms) 


The parameters are explained below: 


6 subcmd 
specifies the subcommand that you want to have clarified. Jd 
6 ALL 
6 FUNCTION 
6 SYNTAX 
6 OPERANDS 
f OPERANDS (parms) 
specifies the explanatory information requested: 


ALL specifies that you want a description of the function, syntax, and the parameters of 
the subcommand that you specified. 


FUNCTION specifies that you want a description of the referenced subcommand’s function. 


SYNTAX specifies that you want a definition of the proper syntax for the referenced 
subcommand. 


OPERANDS specifies that you want an explanation of the parameters applicable to the 
referenced subcommand. 


parms specifies the particular keywords that you want to have explained. If you do not 
specify any keywords, all of the applicable keywords will be included. 


Example 1 


Operation: Have a list of available subcommands displayed at your terminal. 
help 
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Example 2 


Operation: Obtain available information about a particular subcommand. 
h monitor 


Example 3 
Operation: Have a list of the parameters for a particular subcommand displayed at your 
terminal. 


h display operands 


HELP Subcommand of OPERATOR 69 





MONITOR Subcommand of OPERATOR 


Use the MONITOR subcommand to monitor terminal activities and job activities within the 
system. Informational messages will be displayed. The content of the messages will pertain to 
the type of information indicated by the parameter included with the MONITOR subcommand. 
The system will continue to issue these informational messages until halted by a STOPMN 
subcommand or until you terminate the OPERATOR command. 


The MONITOR subcommand of OPERATOR is written as follows: 


MONITOR 
MN 


b One or more blanks must follow MONITOR or MN. 


SESS 
STATUS 
JOBNAMES 


ZK. Note: This parameter may only be specified with SESS or 
JOBNAMES above. 


The parameters are explained below: 


SESS 
STATUS 
JOBNAMES 
specifies the terminal and background job activities to be monitored: 


SESS indicates that you are to be notified whenever any terminal session is initiated or 
terminated. The user’s identification will be displayed at your terminal. If the session 
terminates abnormally, the user identification will appear in the diagnostic message; the 
message ‘user LOGGED OFF’ will not appear if the session was canceled. 


If you specify the T parameter, the system displays the time of day in addition to the 
users identification. The format of the time output is shown under the T parameter 
description. 


STATUS specifies that you want the data set names and volume serial numbers of data sets 
with dispositions of KEEP, CATLG, or UNCATLG to be displayed whenever the data sets 
are freed. 


JOBNAMES specifies that you want the name of each job to be displayed both when the 
job starts and when it terminates, and that you want unit record allocation to be 
displayed when the job step starts. If a job terminates abnormally, the jobname will 
appear in the diagnostic message; the message ‘jobname ENDED’ will not appear. 


If you specify the T parameter with the JOBNAMES parameter, the system displays the 
time of the day in addition to the jobnames. The format of the output is shown under the 
T parameter description. 
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nah 
specifies that you want the time of day to be displayed in the following format. 
hh.mm.ss 
The variables in this format are: 
hh - Hours (00-23) 
mm - Minutes (00-59) 
ss - Seconds (00-59) 


Whenever one TSO user specifies this parameter, all subsequent users of the MONITOR 
command will also receive the time at their terminals. 


Example 1 


Operation: Have the system notify you whenever a terminal session begins or ends. 


monitor sess 


Example 2 
Operation: Have displayed at your terminal the name of each job when the job starts and 


when it terminates. Also have the time displayed with the jobname. 
mn jobnames,t 
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SEND Subcommand of OPERATOR 


Use the SEND subcommand to send a message to one or more terminal users, save a message 
in the SYSI.BRODCAST data set, list, delete, or send a specified message from notices section 
of SYS!.BRODCAST data set, and list all messages in the notices section of SYSI|.BRODCAST 
data set. Messages sent via the SEND subcommand will have the characters OPER appended to 
the message text before it is directed to a user terminal. 


Messages are also sent to the console operator and other terminals in operator mode. The 
characters specified in the CN parameter are appended to a message sent by a console 
operator. 


The SEND subcommand of OPERATOR is written as follows: 


SEND 

SE 

b One or more blanks must follow SEND or SE. 

‘msg’ msg: up to 115 characters. 

msg nmbr msg nmbr: decimal digits. 

LIST Note: If LIST is specified, no other parameters may be specified. 
ALL user ids: 1-7 alphameric characters, beginning with an alphameric 
,USER=(user ids) or national character. ID are separated by commas. 

.BRDCST rte code: decimal digits 1-15. 

,OPERATOR=rte code console id: decimal digits 0-64. 

.CN=console id Default: ALL 

JLIST Note: LIST and DELETE may not be specified with ‘msg’ above. 
DELETE 

NOW Default: NOW 

LOGON Note: This parameter may only be specified with USER above. 
SAVE 


The parameters are explained below: 


5 


‘MSZ 

msg nmbr 

LIST 
specifies the message you want to send (‘msg’) or the number of a notice in the 
SYSI.BRODCAST data set (msg nmbr). LIST specifies that a listing of all the SEND notices 
retained in the system is to be produced at your terminal; each message will be preceded by 
a system-assigned number. 


If ‘msg’ is specified, you must enclose the text of the message within apostrophes (as 
indicated). The message must be contained on one line (you cannot continue a message on 
a second line). If you want a quotation mark printed in the message, you must enter two 
quotation marks. 


ALL 
,USER =fuser ids) 
sBRDCST 
OPERATOR =rte code 
CN =console id 
LIST 
,DELETE 
specifies additional information about the message to be sent: 
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ALL specifies that all terminal users are to receive the message. Terminal users who are 
currently using the system will receive the message immediately. 


USER specifies the user identification of one or more terminal users who are to receive the 
message. The USERID must already exist in the broadcast data set. This is done 
automatically via the ACCOUNT command when updating the UADS. 


BRDCST specifies that the message is to be queued to all active consoles. 


OPERATOR specifies that the message is to be queued to the console associated with the 
routine code assigned. 


CN specifies that the message is to be queued to the operator console indicated by the 
console identification. (The console configuration message issued at IPL can be used for 
reference to determine the appropriate ids.) Console id 0 causes the message to be sent 
to the master console, and is substituted if the specified console id is a 2-digit value 
outside the valid range. 


LIST is defined above. 


DELETE specifies that you want a message to be deleted. 


NOW 
LOGON 
SAVE 
specifies how the message is to be handled: 


NOW specifies that the message is to be sent immediately. If the recipient is not logged on, 
you will be notified and the message will be deleted. 


LOGON specifies that the message is to be sent immediately if the recipients are logged on 
and receiving messages. Otherwise: 


¢ If you specify a user identification, the message is retained in the ''mail'' section of the 
SYS1.BRODCAST data set and deleted by the system after it is sent to the intended user. 

¢ If you specify ''ALL", the message will be stored in the "notices'' section of the 
SYS1.BRODCAST data set and retained there until the operator deletes it. 


SAVE specifies that the message text is to be entered in the appropriate section of the 
SYS1.BRODCAST data set without being sent to any user. If you specify a user 
identification, the message is stored in the mail section of SYS1.BRODCAST data set and is 
deleted by the system after it is sent to the intended user. If you specify ALL, the 
message will be stored in the notices section of SYS1.BRODCAST data set and retained 


there until the operator deletes it. 


Example 1 


Operation: Send a message to all terminal users currently logged on. 


send 'tso to shut down at 9:55 p.m. est 9/14/70' 
Example 2 


Operation: Send a message to two particular terminal users currently logged on. 


send 'your acct no. invalid after this session',user=(heus75,jul165) 
Example 3 


Operation: Delete a message. 
send 8, delete 
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Example 4 


Operation: Wave all messages displayed at your terminal. 


send list 
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STOPMN Subcommand of OPERATOR 


Use the STOPMN subcommand to terminate the monitoring operations of the MONITOR 
subcommand. This subcommand will halt the display of information at your terminal. 


The STOPMN subcommand of OPERATOR is written as follows: 


STOPMN 
PM 


6 One or more blanks must follow STOPMN or PM. 
JOBNAMES 


SESS 
STATUS 


The parameters are explained below: 


JOBNAMES 
SESS 
STATUS 
specifies the monitoring operations to be terminated: 


JOBNAMES specifies that the operations provided by the JOBNAMES parameter of the 
MONITOR subcommand are to be stopped. The system will stop displaying the names as 
they start and end. 


SESS specifies that the operations provided by the SESS parameter of the MONITOR 
subcommand are to be stopped. The system will stop notifying the terminal whenever a 
terminal session is initiated or terminated. 


STATUS specifies that the operations provided by the STATUS parameter of the MONITOR 
subcommand are to be stopped. The system will stop displaying the names and volume 
serial numbers of data sets with dispositions of KEEP, CATLG, or UNCATLG at job step 
end and job end. 


Example 1 


Operation: Stop the display of the names of jobs as they begin execution and as they 
terminate. 


stopmn jobnames 


Example 2 


Operation: Stop the display of starting and stopping of terminal session. 


pm sess 
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